2022/07/21 - Amazon Fraud Detector - 15 updated api methods
Changes The release introduces Account Takeover Insights (ATI) model. The ATI model detects fraud relating to account takeover. This release also adds support for new variable types: ARE_CREDENTIALS_VALID and SESSION_ID and adds new structures to Model Version APIs.
{'modelVersions': {'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}}
Creates a detector version. The detector version starts in a DRAFT status.
See also: AWS API Documentation
Request Syntax
client.create_detector_version(
detectorId='string',
description='string',
externalModelEndpoints=[
'string',
],
rules=[
{
'detectorId': 'string',
'ruleId': 'string',
'ruleVersion': 'string'
},
],
modelVersions=[
{
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'modelVersionNumber': 'string',
'arn': 'string'
},
],
ruleExecutionMode='ALL_MATCHED'|'FIRST_MATCHED',
tags=[
{
'key': 'string',
'value': 'string'
},
]
)
string
[REQUIRED]
The ID of the detector under which you want to create a new version.
string
The description of the detector version.
list
The Amazon Sagemaker model endpoints to include in the detector version.
(string) --
list
[REQUIRED]
The rules to include in the detector version.
(dict) --
A rule.
detectorId (string) -- [REQUIRED]
The detector for which the rule is associated.
ruleId (string) -- [REQUIRED]
The rule ID.
ruleVersion (string) -- [REQUIRED]
The rule version.
list
The model versions to include in the detector version.
(dict) --
The model version.
modelId (string) -- [REQUIRED]
The model ID.
modelType (string) -- [REQUIRED]
The model type.
modelVersionNumber (string) -- [REQUIRED]
The model version number.
arn (string) --
The model version ARN.
string
The rule execution mode for the rules included in the detector version.
You can define and edit the rule mode at the detector version level, when it is in draft status.
If you specify FIRST_MATCHED, Amazon Fraud Detector evaluates rules sequentially, first to last, stopping at the first matched rule. Amazon Fraud dectector then provides the outcomes for that single rule.
If you specifiy ALL_MATCHED, Amazon Fraud Detector evaluates all rules and returns the outcomes for all matched rules.
The default behavior is FIRST_MATCHED.
list
A collection of key and value pairs.
(dict) --
A key and value pair.
key (string) -- [REQUIRED]
A tag key.
value (string) -- [REQUIRED]
A value assigned to a tag key.
dict
Response Syntax
{
'detectorId': 'string',
'detectorVersionId': 'string',
'status': 'DRAFT'|'ACTIVE'|'INACTIVE'
}
Response Structure
(dict) --
detectorId (string) --
The ID for the created version's parent detector.
detectorVersionId (string) --
The ID for the created detector.
status (string) --
The status of the detector version.
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Creates a model using the specified model type.
See also: AWS API Documentation
Request Syntax
client.create_model(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
description='string',
eventTypeName='string',
tags=[
{
'key': 'string',
'value': 'string'
},
]
)
string
[REQUIRED]
The model ID.
string
[REQUIRED]
The model type.
string
The model description.
string
[REQUIRED]
The name of the event type.
list
A collection of key and value pairs.
(dict) --
A key and value pair.
key (string) -- [REQUIRED]
A tag key.
value (string) -- [REQUIRED]
A value assigned to a tag key.
dict
Response Syntax
{}
Response Structure
(dict) --
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Creates a version of the model using the specified model type and model id.
See also: AWS API Documentation
Request Syntax
client.create_model_version(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
trainingDataSource='EXTERNAL_EVENTS'|'INGESTED_EVENTS',
trainingDataSchema={
'modelVariables': [
'string',
],
'labelSchema': {
'labelMapper': {
'string': [
'string',
]
},
'unlabeledEventsTreatment': 'IGNORE'|'FRAUD'|'LEGIT'
}
},
externalEventsDetail={
'dataLocation': 'string',
'dataAccessRoleArn': 'string'
},
ingestedEventsDetail={
'ingestedEventsTimeWindow': {
'startTime': 'string',
'endTime': 'string'
}
},
tags=[
{
'key': 'string',
'value': 'string'
},
]
)
string
[REQUIRED]
The model ID.
string
[REQUIRED]
The model type.
string
[REQUIRED]
The training data source location in Amazon S3.
dict
[REQUIRED]
The training data schema.
modelVariables (list) -- [REQUIRED]
The training data schema variables.
(string) --
labelSchema (dict) --
The label schema.
labelMapper (dict) --
The label mapper maps the Amazon Fraud Detector supported model classification labels ( FRAUD, LEGIT) to the appropriate event type labels. For example, if " FRAUD" and " LEGIT" are Amazon Fraud Detector supported labels, this mapper could be: {"FRAUD" => ["0"], "LEGIT" => ["1"]} or {"FRAUD" => ["false"], "LEGIT" => ["true"]} or {"FRAUD" => ["fraud", "abuse"], "LEGIT" => ["legit", "safe"]}. The value part of the mapper is a list, because you may have multiple label variants from your event type for a single Amazon Fraud Detector label.
(string) --
(list) --
(string) --
unlabeledEventsTreatment (string) --
The action to take for unlabeled events.
dict
Details of the external events data used for model version training. Required if trainingDataSource is EXTERNAL_EVENTS.
dataLocation (string) -- [REQUIRED]
The Amazon S3 bucket location for the data.
dataAccessRoleArn (string) -- [REQUIRED]
The ARN of the role that provides Amazon Fraud Detector access to the data location.
dict
Details of the ingested events data used for model version training. Required if trainingDataSource is INGESTED_EVENTS.
ingestedEventsTimeWindow (dict) -- [REQUIRED]
The start and stop time of the ingested events.
startTime (string) -- [REQUIRED]
Timestamp of the first ingensted event.
endTime (string) -- [REQUIRED]
Timestamp of the final ingested event.
list
A collection of key and value pairs.
(dict) --
A key and value pair.
key (string) -- [REQUIRED]
A tag key.
value (string) -- [REQUIRED]
A value assigned to a tag key.
dict
Response Syntax
{
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'modelVersionNumber': 'string',
'status': 'string'
}
Response Structure
(dict) --
modelId (string) --
The model ID.
modelType (string) --
The model type.
modelVersionNumber (string) --
The model version number of the model version created.
status (string) --
The model version status.
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Deletes a model.
You can delete models and model versions in Amazon Fraud Detector, provided that they are not associated with a detector version.
When you delete a model, Amazon Fraud Detector permanently deletes that model and the data is no longer stored in Amazon Fraud Detector.
See also: AWS API Documentation
Request Syntax
client.delete_model(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS'
)
string
[REQUIRED]
The model ID of the model to delete.
string
[REQUIRED]
The model type of the model to delete.
dict
Response Syntax
{}
Response Structure
(dict) --
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Deletes a model version.
You can delete models and model versions in Amazon Fraud Detector, provided that they are not associated with a detector version.
When you delete a model version, Amazon Fraud Detector permanently deletes that model version and the data is no longer stored in Amazon Fraud Detector.
See also: AWS API Documentation
Request Syntax
client.delete_model_version(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
modelVersionNumber='string'
)
string
[REQUIRED]
The model ID of the model version to delete.
string
[REQUIRED]
The model type of the model version to delete.
string
[REQUIRED]
The model version number of the model version to delete.
dict
Response Syntax
{}
Response Structure
(dict) --
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Response {'modelVersionDetails': {'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'},
'trainingResultV2': {'aggregatedVariablesImportanceMetrics': {'logOddsMetrics': [{'aggregatedVariablesImportance': 'float',
'variableNames': ['string']}]},
'dataValidationMetrics': {'fieldLevelMessages': [{'content': 'string',
'fieldName': 'string',
'identifier': 'string',
'title': 'string',
'type': 'string'}],
'fileLevelMessages': [{'content': 'string',
'title': 'string',
'type': 'string'}]},
'trainingMetricsV2': {'ati': {'metricDataPoints': [{'adr': 'float',
'atodr': 'float',
'cr': 'float',
'threshold': 'float'}],
'modelPerformance': {'asi': 'float'}},
'ofi': {'metricDataPoints': [{'fpr': 'float',
'precision': 'float',
'threshold': 'float',
'tpr': 'float'}],
'modelPerformance': {'auc': 'float'}},
'tfi': {'metricDataPoints': [{'fpr': 'float',
'precision': 'float',
'threshold': 'float',
'tpr': 'float'}],
'modelPerformance': {'auc': 'float'}}},
'variableImportanceMetrics': {'logOddsMetrics': [{'variableImportance': 'float',
'variableName': 'string',
'variableType': 'string'}]}}}}
Gets all of the model versions for the specified model type or for the specified model type and model ID. You can also get details for a single, specified model version.
See also: AWS API Documentation
Request Syntax
client.describe_model_versions(
modelId='string',
modelVersionNumber='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
nextToken='string',
maxResults=123
)
string
The model ID.
string
The model version number.
string
The model type.
string
The next token from the previous results.
integer
The maximum number of results to return.
dict
Response Syntax
{
'modelVersionDetails': [
{
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'modelVersionNumber': 'string',
'status': 'string',
'trainingDataSource': 'EXTERNAL_EVENTS'|'INGESTED_EVENTS',
'trainingDataSchema': {
'modelVariables': [
'string',
],
'labelSchema': {
'labelMapper': {
'string': [
'string',
]
},
'unlabeledEventsTreatment': 'IGNORE'|'FRAUD'|'LEGIT'
}
},
'externalEventsDetail': {
'dataLocation': 'string',
'dataAccessRoleArn': 'string'
},
'ingestedEventsDetail': {
'ingestedEventsTimeWindow': {
'startTime': 'string',
'endTime': 'string'
}
},
'trainingResult': {
'dataValidationMetrics': {
'fileLevelMessages': [
{
'title': 'string',
'content': 'string',
'type': 'string'
},
],
'fieldLevelMessages': [
{
'fieldName': 'string',
'identifier': 'string',
'title': 'string',
'content': 'string',
'type': 'string'
},
]
},
'trainingMetrics': {
'auc': ...,
'metricDataPoints': [
{
'fpr': ...,
'precision': ...,
'tpr': ...,
'threshold': ...
},
]
},
'variableImportanceMetrics': {
'logOddsMetrics': [
{
'variableName': 'string',
'variableType': 'string',
'variableImportance': ...
},
]
}
},
'lastUpdatedTime': 'string',
'createdTime': 'string',
'arn': 'string',
'trainingResultV2': {
'dataValidationMetrics': {
'fileLevelMessages': [
{
'title': 'string',
'content': 'string',
'type': 'string'
},
],
'fieldLevelMessages': [
{
'fieldName': 'string',
'identifier': 'string',
'title': 'string',
'content': 'string',
'type': 'string'
},
]
},
'trainingMetricsV2': {
'ofi': {
'metricDataPoints': [
{
'fpr': ...,
'precision': ...,
'tpr': ...,
'threshold': ...
},
],
'modelPerformance': {
'auc': ...
}
},
'tfi': {
'metricDataPoints': [
{
'fpr': ...,
'precision': ...,
'tpr': ...,
'threshold': ...
},
],
'modelPerformance': {
'auc': ...
}
},
'ati': {
'metricDataPoints': [
{
'cr': ...,
'adr': ...,
'threshold': ...,
'atodr': ...
},
],
'modelPerformance': {
'asi': ...
}
}
},
'variableImportanceMetrics': {
'logOddsMetrics': [
{
'variableName': 'string',
'variableType': 'string',
'variableImportance': ...
},
]
},
'aggregatedVariablesImportanceMetrics': {
'logOddsMetrics': [
{
'variableNames': [
'string',
],
'aggregatedVariablesImportance': ...
},
]
}
}
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
modelVersionDetails (list) --
The model version details.
(dict) --
The details of the model version.
modelId (string) --
The model ID.
modelType (string) --
The model type.
modelVersionNumber (string) --
The model version number.
status (string) --
The status of the model version.
trainingDataSource (string) --
The model version training data source.
trainingDataSchema (dict) --
The training data schema.
modelVariables (list) --
The training data schema variables.
(string) --
labelSchema (dict) --
The label schema.
labelMapper (dict) --
The label mapper maps the Amazon Fraud Detector supported model classification labels ( FRAUD, LEGIT) to the appropriate event type labels. For example, if " FRAUD" and " LEGIT" are Amazon Fraud Detector supported labels, this mapper could be: {"FRAUD" => ["0"], "LEGIT" => ["1"]} or {"FRAUD" => ["false"], "LEGIT" => ["true"]} or {"FRAUD" => ["fraud", "abuse"], "LEGIT" => ["legit", "safe"]}. The value part of the mapper is a list, because you may have multiple label variants from your event type for a single Amazon Fraud Detector label.
(string) --
(list) --
(string) --
unlabeledEventsTreatment (string) --
The action to take for unlabeled events.
externalEventsDetail (dict) --
The external events data details. This will be populated if the trainingDataSource for the model version is specified as EXTERNAL_EVENTS.
dataLocation (string) --
The Amazon S3 bucket location for the data.
dataAccessRoleArn (string) --
The ARN of the role that provides Amazon Fraud Detector access to the data location.
ingestedEventsDetail (dict) --
The ingested events data details. This will be populated if the trainingDataSource for the model version is specified as INGESTED_EVENTS.
ingestedEventsTimeWindow (dict) --
The start and stop time of the ingested events.
startTime (string) --
Timestamp of the first ingensted event.
endTime (string) --
Timestamp of the final ingested event.
trainingResult (dict) --
The training results.
dataValidationMetrics (dict) --
The validation metrics.
fileLevelMessages (list) --
The file-specific model training data validation messages.
(dict) --
The message details.
title (string) --
The message title.
content (string) --
The message content.
type (string) --
The message type.
fieldLevelMessages (list) --
The field-specific model training validation messages.
(dict) --
The message details.
fieldName (string) --
The field name.
identifier (string) --
The message ID.
title (string) --
The message title.
content (string) --
The message content.
type (string) --
The message type.
trainingMetrics (dict) --
The training metric details.
auc (float) --
The area under the curve. This summarizes true positive rate (TPR) and false positive rate (FPR) across all possible model score thresholds. A model with no predictive power has an AUC of 0.5, whereas a perfect model has a score of 1.0.
metricDataPoints (list) --
The data points details.
(dict) --
Model performance metrics data points.
fpr (float) --
The false positive rate. This is the percentage of total legitimate events that are incorrectly predicted as fraud.
precision (float) --
The percentage of fraud events correctly predicted as fraudulent as compared to all events predicted as fraudulent.
tpr (float) --
The true positive rate. This is the percentage of total fraud the model detects. Also known as capture rate.
threshold (float) --
The model threshold that specifies an acceptable fraud capture rate. For example, a threshold of 500 means any model score 500 or above is labeled as fraud.
variableImportanceMetrics (dict) --
The variable importance metrics.
logOddsMetrics (list) --
List of variable metrics.
(dict) --
The log odds metric details.
variableName (string) --
The name of the variable.
variableType (string) --
The type of variable.
variableImportance (float) --
The relative importance of the variable. For more information, see Model variable importance.
lastUpdatedTime (string) --
The timestamp when the model was last updated.
createdTime (string) --
The timestamp when the model was created.
arn (string) --
The model version ARN.
trainingResultV2 (dict) --
The training result details. The details include the relative importance of the variables.
dataValidationMetrics (dict) --
The model training data validation metrics.
fileLevelMessages (list) --
The file-specific model training data validation messages.
(dict) --
The message details.
title (string) --
The message title.
content (string) --
The message content.
type (string) --
The message type.
fieldLevelMessages (list) --
The field-specific model training validation messages.
(dict) --
The message details.
fieldName (string) --
The field name.
identifier (string) --
The message ID.
title (string) --
The message title.
content (string) --
The message content.
type (string) --
The message type.
trainingMetricsV2 (dict) --
The training metric details.
ofi (dict) --
The Online Fraud Insights (OFI) model training metric details.
metricDataPoints (list) --
The model's performance metrics data points.
(dict) --
The Online Fraud Insights (OFI) model performance metrics data points.
fpr (float) --
The false positive rate. This is the percentage of total legitimate events that are incorrectly predicted as fraud.
precision (float) --
The percentage of fraud events correctly predicted as fraudulent as compared to all events predicted as fraudulent.
tpr (float) --
The true positive rate. This is the percentage of total fraud the model detects. Also known as capture rate.
threshold (float) --
The model threshold that specifies an acceptable fraud capture rate. For example, a threshold of 500 means any model score 500 or above is labeled as fraud.
modelPerformance (dict) --
The model's overall performance score.
auc (float) --
The area under the curve (auc). This summarizes the total positive rate (tpr) and false positive rate (FPR) across all possible model score thresholds.
tfi (dict) --
The Transaction Fraud Insights (TFI) model training metric details.
metricDataPoints (list) --
The model's performance metrics data points.
(dict) --
The performance metrics data points for Transaction Fraud Insights (TFI) model.
fpr (float) --
The false positive rate. This is the percentage of total legitimate events that are incorrectly predicted as fraud.
precision (float) --
The percentage of fraud events correctly predicted as fraudulent as compared to all events predicted as fraudulent.
tpr (float) --
The true positive rate. This is the percentage of total fraud the model detects. Also known as capture rate.
threshold (float) --
The model threshold that specifies an acceptable fraud capture rate. For example, a threshold of 500 means any model score 500 or above is labeled as fraud.
modelPerformance (dict) --
The model performance score.
auc (float) --
The area under the curve (auc). This summarizes the total positive rate (tpr) and false positive rate (FPR) across all possible model score thresholds.
ati (dict) --
The Account Takeover Insights (ATI) model training metric details.
metricDataPoints (list) --
The model's performance metrics data points.
(dict) --
The Account Takeover Insights (ATI) model performance metrics data points.
cr (float) --
The challenge rate. This indicates the percentage of login events that the model recommends to challenge such as one-time password, multi-factor authentication, and investigations.
adr (float) --
The anomaly discovery rate. This metric quantifies the percentage of anomalies that can be detected by the model at the selected score threshold. A lower score threshold increases the percentage of anomalies captured by the model, but would also require challenging a larger percentage of login events, leading to a higher customer friction.
threshold (float) --
The model's threshold that specifies an acceptable fraud capture rate. For example, a threshold of 500 means any model score 500 or above is labeled as fraud.
atodr (float) --
The account takeover discovery rate. This metric quantifies the percentage of account compromise events that can be detected by the model at the selected score threshold. This metric is only available if 50 or more entities with at-least one labeled account takeover event is present in the ingested dataset.
modelPerformance (dict) --
The model's overall performance scores.
asi (float) --
The anomaly separation index (ASI) score. This metric summarizes the overall ability of the model to separate anomalous activities from the normal behavior. Depending on the business, a large fraction of these anomalous activities can be malicious and correspond to the account takeover attacks. A model with no separability power will have the lowest possible ASI score of 0.5, whereas the a model with a high separability power will have the highest possible ASI score of 1.0
variableImportanceMetrics (dict) --
The variable importance metrics details.
logOddsMetrics (list) --
List of variable metrics.
(dict) --
The log odds metric details.
variableName (string) --
The name of the variable.
variableType (string) --
The type of variable.
variableImportance (float) --
The relative importance of the variable. For more information, see Model variable importance.
aggregatedVariablesImportanceMetrics (dict) --
The variable importance metrics of the aggregated variables.
Account Takeover Insights (ATI) model uses event variables from the login data you provide to continuously calculate a set of variables (aggregated variables) based on historical events. For example, your ATI model might calculate the number of times an user has logged in using the same IP address. In this case, event variables used to derive the aggregated variables are IP address and user.
logOddsMetrics (list) --
List of variables' metrics.
(dict) --
The log odds metric details.
Account Takeover Insights (ATI) model uses event variables from the login data you provide to continuously calculate a set of variables (aggregated variables) based on historical events. For example, your ATI model might calculate the number of times an user has logged in using the same IP address. In this case, event variables used to derive the aggregated variables are IP address and user.
variableNames (list) --
The names of all the variables.
(string) --
aggregatedVariablesImportance (float) --
The relative importance of the variables in the list to the other event variable.
nextToken (string) --
The next token.
{'modelVersions': {'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}}
Gets a particular detector version.
See also: AWS API Documentation
Request Syntax
client.get_detector_version(
detectorId='string',
detectorVersionId='string'
)
string
[REQUIRED]
The detector ID.
string
[REQUIRED]
The detector version ID.
dict
Response Syntax
{
'detectorId': 'string',
'detectorVersionId': 'string',
'description': 'string',
'externalModelEndpoints': [
'string',
],
'modelVersions': [
{
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'modelVersionNumber': 'string',
'arn': 'string'
},
],
'rules': [
{
'detectorId': 'string',
'ruleId': 'string',
'ruleVersion': 'string'
},
],
'status': 'DRAFT'|'ACTIVE'|'INACTIVE',
'lastUpdatedTime': 'string',
'createdTime': 'string',
'ruleExecutionMode': 'ALL_MATCHED'|'FIRST_MATCHED',
'arn': 'string'
}
Response Structure
(dict) --
detectorId (string) --
The detector ID.
detectorVersionId (string) --
The detector version ID.
description (string) --
The detector version description.
externalModelEndpoints (list) --
The Amazon SageMaker model endpoints included in the detector version.
(string) --
modelVersions (list) --
The model versions included in the detector version.
(dict) --
The model version.
modelId (string) --
The model ID.
modelType (string) --
The model type.
modelVersionNumber (string) --
The model version number.
arn (string) --
The model version ARN.
rules (list) --
The rules included in the detector version.
(dict) --
A rule.
detectorId (string) --
The detector for which the rule is associated.
ruleId (string) --
The rule ID.
ruleVersion (string) --
The rule version.
status (string) --
The status of the detector version.
lastUpdatedTime (string) --
The timestamp when the detector version was last updated.
createdTime (string) --
The timestamp when the detector version was created.
ruleExecutionMode (string) --
The execution mode of the rule in the dectector
FIRST_MATCHED indicates that Amazon Fraud Detector evaluates rules sequentially, first to last, stopping at the first matched rule. Amazon Fraud dectector then provides the outcomes for that single rule.
ALL_MATCHED indicates that Amazon Fraud Detector evaluates all rules and returns the outcomes for all matched rules. You can define and edit the rule mode at the detector version level, when it is in draft status.
arn (string) --
The detector version ARN.
{'modelScores': {'modelVersion': {'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}}}
Evaluates an event against a detector version. If a version ID is not provided, the detector’s ( ACTIVE) version is used.
See also: AWS API Documentation
Request Syntax
client.get_event_prediction(
detectorId='string',
detectorVersionId='string',
eventId='string',
eventTypeName='string',
entities=[
{
'entityType': 'string',
'entityId': 'string'
},
],
eventTimestamp='string',
eventVariables={
'string': 'string'
},
externalModelEndpointDataBlobs={
'string': {
'byteBuffer': b'bytes',
'contentType': 'string'
}
}
)
string
[REQUIRED]
The detector ID.
string
The detector version ID.
string
[REQUIRED]
The unique ID used to identify the event.
string
[REQUIRED]
The event type associated with the detector specified for the prediction.
list
[REQUIRED]
The entity type (associated with the detector's event type) and specific entity ID representing who performed the event. If an entity id is not available, use "UNKNOWN."
(dict) --
The entity details.
entityType (string) -- [REQUIRED]
The entity type.
entityId (string) -- [REQUIRED]
The entity ID. If you do not know the entityId, you can pass unknown, which is areserved string literal.
string
[REQUIRED]
Timestamp that defines when the event under evaluation occurred. The timestamp must be specified using ISO 8601 standard in UTC.
dict
[REQUIRED]
Names of the event type's variables you defined in Amazon Fraud Detector to represent data elements and their corresponding values for the event you are sending for evaluation.
To ensure most accurate fraud prediction and to simplify your data preparation, Amazon Fraud Detector will replace all missing variables or values as follows:
For Amazon Fraud Detector trained models:
If a null value is provided explicitly for a variable or if a variable is missing, model will replace the null value or the missing variable (no variable name in the eventVariables map) with calculated default mean/medians for numeric variables and with special values for categorical variables.
For imported SageMaker models:
If a null value is provided explicitly for a variable, the model and rules will use “null” as the value. If a variable is not provided (no variable name in the eventVariables map), model and rules will use the default value that is provided for the variable.
(string) --
(string) --
dict
The Amazon SageMaker model endpoint input data blobs.
(string) --
(dict) --
A pre-formed Amazon SageMaker model input you can include if your detector version includes an imported Amazon SageMaker model endpoint with pass-through input configuration.
byteBuffer (bytes) --
The byte buffer of the Amazon SageMaker model endpoint input data blob.
contentType (string) --
The content type of the Amazon SageMaker model endpoint input data blob.
dict
Response Syntax
{
'modelScores': [
{
'modelVersion': {
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'modelVersionNumber': 'string',
'arn': 'string'
},
'scores': {
'string': ...
}
},
],
'ruleResults': [
{
'ruleId': 'string',
'outcomes': [
'string',
]
},
],
'externalModelOutputs': [
{
'externalModel': {
'modelEndpoint': 'string',
'modelSource': 'SAGEMAKER'
},
'outputs': {
'string': 'string'
}
},
]
}
Response Structure
(dict) --
modelScores (list) --
The model scores. Amazon Fraud Detector generates model scores between 0 and 1000, where 0 is low fraud risk and 1000 is high fraud risk. Model scores are directly related to the false positive rate (FPR). For example, a score of 600 corresponds to an estimated 10% false positive rate whereas a score of 900 corresponds to an estimated 2% false positive rate.
(dict) --
The fraud prediction scores.
modelVersion (dict) --
The model version.
modelId (string) --
The model ID.
modelType (string) --
The model type.
modelVersionNumber (string) --
The model version number.
arn (string) --
The model version ARN.
scores (dict) --
The model's fraud prediction scores.
(string) --
(float) --
ruleResults (list) --
The results from the rules.
(dict) --
The rule results.
ruleId (string) --
The rule ID that was matched, based on the rule execution mode.
outcomes (list) --
The outcomes of the matched rule, based on the rule execution mode.
(string) --
externalModelOutputs (list) --
The model scores for Amazon SageMaker models.
(dict) --
The fraud prediction scores from Amazon SageMaker model.
externalModel (dict) --
The Amazon SageMaker model.
modelEndpoint (string) --
The endpoint of the Amazon SageMaker model.
modelSource (string) --
The source of the model.
outputs (dict) --
The fraud prediction scores from Amazon SageMaker model.
(string) --
(string) --
{'evaluatedModelVersions': {'evaluations': {'predictionExplanations': {'aggregatedVariablesImpactExplanations': [{'eventVariableNames': ['string'],
'logOddsImpact': 'float',
'relativeImpact': 'string'}]}}}}
Gets details of the past fraud predictions for the specified event ID, event type, detector ID, and detector version ID that was generated in the specified time period.
See also: AWS API Documentation
Request Syntax
client.get_event_prediction_metadata(
eventId='string',
eventTypeName='string',
detectorId='string',
detectorVersionId='string',
predictionTimestamp='string'
)
string
[REQUIRED]
The event ID.
string
[REQUIRED]
The event type associated with the detector specified for the prediction.
string
[REQUIRED]
The detector ID.
string
[REQUIRED]
The detector version ID.
string
[REQUIRED]
The timestamp that defines when the prediction was generated. The timestamp must be specified using ISO 8601 standard in UTC.
We recommend calling ListEventPredictions first, and using the predictionTimestamp value in the response to provide an accurate prediction timestamp value.
dict
Response Syntax
{
'eventId': 'string',
'eventTypeName': 'string',
'entityId': 'string',
'entityType': 'string',
'eventTimestamp': 'string',
'detectorId': 'string',
'detectorVersionId': 'string',
'detectorVersionStatus': 'string',
'eventVariables': [
{
'name': 'string',
'value': 'string',
'source': 'string'
},
],
'rules': [
{
'ruleId': 'string',
'ruleVersion': 'string',
'expression': 'string',
'expressionWithValues': 'string',
'outcomes': [
'string',
],
'evaluated': True|False,
'matched': True|False
},
],
'ruleExecutionMode': 'ALL_MATCHED'|'FIRST_MATCHED',
'outcomes': [
'string',
],
'evaluatedModelVersions': [
{
'modelId': 'string',
'modelVersion': 'string',
'modelType': 'string',
'evaluations': [
{
'outputVariableName': 'string',
'evaluationScore': 'string',
'predictionExplanations': {
'variableImpactExplanations': [
{
'eventVariableName': 'string',
'relativeImpact': 'string',
'logOddsImpact': ...
},
],
'aggregatedVariablesImpactExplanations': [
{
'eventVariableNames': [
'string',
],
'relativeImpact': 'string',
'logOddsImpact': ...
},
]
}
},
]
},
],
'evaluatedExternalModels': [
{
'modelEndpoint': 'string',
'useEventVariables': True|False,
'inputVariables': {
'string': 'string'
},
'outputVariables': {
'string': 'string'
}
},
],
'predictionTimestamp': 'string'
}
Response Structure
(dict) --
eventId (string) --
The event ID.
eventTypeName (string) --
The event type associated with the detector specified for this prediction.
entityId (string) --
The entity ID.
entityType (string) --
The entity type.
eventTimestamp (string) --
The timestamp for when the prediction was generated for the associated event ID.
detectorId (string) --
The detector ID.
detectorVersionId (string) --
The detector version ID.
detectorVersionStatus (string) --
The status of the detector version.
eventVariables (list) --
A list of event variables that influenced the prediction scores.
(dict) --
Information about the summary of an event variable that was evaluated for generating prediction.
name (string) --
The event variable name.
value (string) --
The value of the event variable.
source (string) --
The event variable source.
rules (list) --
List of rules associated with the detector version that were used for evaluating variable values.
(dict) --
The details of the rule used for evaluating variable values.
ruleId (string) --
The rule ID.
ruleVersion (string) --
The rule version.
expression (string) --
The rule expression.
expressionWithValues (string) --
The rule expression value.
outcomes (list) --
The rule outcome.
(string) --
evaluated (boolean) --
Indicates whether the rule was evaluated.
matched (boolean) --
Indicates whether the rule matched.
ruleExecutionMode (string) --
The execution mode of the rule used for evaluating variable values.
outcomes (list) --
The outcomes of the matched rule, based on the rule execution mode.
(string) --
evaluatedModelVersions (list) --
Model versions that were evaluated for generating predictions.
(dict) --
The model version evaluated for generating prediction.
modelId (string) --
The model ID.
modelVersion (string) --
The model version.
modelType (string) --
The model type.
Valid values: ONLINE_FRAUD_INSIGHTS | TRANSACTION_FRAUD_INSIGHTS
evaluations (list) --
Evaluations generated for the model version.
(dict) --
The model version evalutions.
outputVariableName (string) --
The output variable name.
evaluationScore (string) --
The evaluation score generated for the model version.
predictionExplanations (dict) --
The prediction explanations generated for the model version.
variableImpactExplanations (list) --
The details of the event variable's impact on the prediction score.
(dict) --
The details of the event variable's impact on the prediction score.
eventVariableName (string) --
The event variable name.
relativeImpact (string) --
The event variable's relative impact in terms of magnitude on the prediction scores. The relative impact values consist of a numerical rating (0-5, 5 being the highest) and direction (increased/decreased) impact of the fraud risk.
logOddsImpact (float) --
The raw, uninterpreted value represented as log-odds of the fraud. These values are usually between -10 to +10, but range from - infinity to + 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.
aggregatedVariablesImpactExplanations (list) --
The details of the aggregated variables impact on the prediction score.
Account Takeover Insights (ATI) model uses event variables from the login data you provide to continuously calculate a set of variables (aggregated variables) based on historical events. For example, your ATI model might calculate the number of times an user has logged in using the same IP address. In this case, event variables used to derive the aggregated variables are IP address and user.
(dict) --
The details of the impact of aggregated variables on the prediction score.
Account Takeover Insights (ATI) model uses the login data you provide to continuously calculate a set of variables (aggregated variables) based on historical events. For example, the model might calculate the number of times an user has logged in using the same IP address. In this case, event variables used to derive the aggregated variables are IP address and user.
eventVariableNames (list) --
The names of all the event variables that were used to derive the aggregated variables.
(string) --
relativeImpact (string) --
The relative impact of the aggregated variables in terms of magnitude on the prediction scores.
logOddsImpact (float) --
The raw, uninterpreted value represented as log-odds of the fraud. These values are usually between -10 to +10, but range from -infinity to +infinity.
A positive value indicates that the variables drove the risk score up.
A negative value indicates that the variables drove the risk score down.
evaluatedExternalModels (list) --
External (Amazon SageMaker) models that were evaluated for generating predictions.
(dict) --
The details of the external (Amazon Sagemaker) model evaluated for generating predictions.
modelEndpoint (string) --
The endpoint of the external (Amazon Sagemaker) model.
useEventVariables (boolean) --
Indicates whether event variables were used to generate predictions.
inputVariables (dict) --
Input variables use for generating predictions.
(string) --
(string) --
outputVariables (dict) --
Output variables.
(string) --
(string) --
predictionTimestamp (string) --
The timestamp that defines when the prediction was generated.
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Gets the details of the specified model version.
See also: AWS API Documentation
Request Syntax
client.get_model_version(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
modelVersionNumber='string'
)
string
[REQUIRED]
The model ID.
string
[REQUIRED]
The model type.
string
[REQUIRED]
The model version number.
dict
Response Syntax
{
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'modelVersionNumber': 'string',
'trainingDataSource': 'EXTERNAL_EVENTS'|'INGESTED_EVENTS',
'trainingDataSchema': {
'modelVariables': [
'string',
],
'labelSchema': {
'labelMapper': {
'string': [
'string',
]
},
'unlabeledEventsTreatment': 'IGNORE'|'FRAUD'|'LEGIT'
}
},
'externalEventsDetail': {
'dataLocation': 'string',
'dataAccessRoleArn': 'string'
},
'ingestedEventsDetail': {
'ingestedEventsTimeWindow': {
'startTime': 'string',
'endTime': 'string'
}
},
'status': 'string',
'arn': 'string'
}
Response Structure
(dict) --
modelId (string) --
The model ID.
modelType (string) --
The model type.
modelVersionNumber (string) --
The model version number.
trainingDataSource (string) --
The training data source.
trainingDataSchema (dict) --
The training data schema.
modelVariables (list) --
The training data schema variables.
(string) --
labelSchema (dict) --
The label schema.
labelMapper (dict) --
The label mapper maps the Amazon Fraud Detector supported model classification labels ( FRAUD, LEGIT) to the appropriate event type labels. For example, if " FRAUD" and " LEGIT" are Amazon Fraud Detector supported labels, this mapper could be: {"FRAUD" => ["0"], "LEGIT" => ["1"]} or {"FRAUD" => ["false"], "LEGIT" => ["true"]} or {"FRAUD" => ["fraud", "abuse"], "LEGIT" => ["legit", "safe"]}. The value part of the mapper is a list, because you may have multiple label variants from your event type for a single Amazon Fraud Detector label.
(string) --
(list) --
(string) --
unlabeledEventsTreatment (string) --
The action to take for unlabeled events.
externalEventsDetail (dict) --
The details of the external events data used for training the model version. This will be populated if the trainingDataSource is EXTERNAL_EVENTS
dataLocation (string) --
The Amazon S3 bucket location for the data.
dataAccessRoleArn (string) --
The ARN of the role that provides Amazon Fraud Detector access to the data location.
ingestedEventsDetail (dict) --
The details of the ingested events data used for training the model version. This will be populated if the trainingDataSource is INGESTED_EVENTS.
ingestedEventsTimeWindow (dict) --
The start and stop time of the ingested events.
startTime (string) --
Timestamp of the first ingensted event.
endTime (string) --
Timestamp of the final ingested event.
status (string) --
The model version status.
Possible values are:
TRAINING_IN_PROGRESS
TRAINING_COMPLETE
ACTIVATE_REQUESTED
ACTIVATE_IN_PROGRESS
ACTIVE
INACTIVATE_REQUESTED
INACTIVATE_IN_PROGRESS
INACTIVE
ERROR
arn (string) --
The model version ARN.
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Response {'models': {'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}}
Gets one or more models. Gets all models for the Amazon Web Services account if no model type and no model id provided. Gets all models for the Amazon Web Services account and model type, if the model type is specified but model id is not provided. Gets a specific model if (model type, model id) tuple is specified.
This is a paginated API. If you provide a null maxResults, this action retrieves a maximum of 10 records per page. If you provide a maxResults, the value must be between 1 and 10. To get the next page results, provide the pagination token from the response as part of your request. A null pagination token fetches the records from the beginning.
See also: AWS API Documentation
Request Syntax
client.get_models(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
nextToken='string',
maxResults=123
)
string
The model ID.
string
The model type.
string
The next token for the subsequent request.
integer
The maximum number of objects to return for the request.
dict
Response Syntax
{
'nextToken': 'string',
'models': [
{
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'description': 'string',
'eventTypeName': 'string',
'createdTime': 'string',
'lastUpdatedTime': 'string',
'arn': 'string'
},
]
}
Response Structure
(dict) --
nextToken (string) --
The next page token to be used in subsequent requests.
models (list) --
The array of models.
(dict) --
The model.
modelId (string) --
The model ID.
modelType (string) --
The model type.
description (string) --
The model description.
eventTypeName (string) --
The name of the event type.
createdTime (string) --
Timestamp of when the model was created.
lastUpdatedTime (string) --
Timestamp of last time the model was updated.
arn (string) --
The ARN of the model.
{'modelVersions': {'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}}
Updates a detector version. The detector version attributes that you can update include models, external model endpoints, rules, rule execution mode, and description. You can only update a DRAFT detector version.
See also: AWS API Documentation
Request Syntax
client.update_detector_version(
detectorId='string',
detectorVersionId='string',
externalModelEndpoints=[
'string',
],
rules=[
{
'detectorId': 'string',
'ruleId': 'string',
'ruleVersion': 'string'
},
],
description='string',
modelVersions=[
{
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'modelVersionNumber': 'string',
'arn': 'string'
},
],
ruleExecutionMode='ALL_MATCHED'|'FIRST_MATCHED'
)
string
[REQUIRED]
The parent detector ID for the detector version you want to update.
string
[REQUIRED]
The detector version ID.
list
[REQUIRED]
The Amazon SageMaker model endpoints to include in the detector version.
(string) --
list
[REQUIRED]
The rules to include in the detector version.
(dict) --
A rule.
detectorId (string) -- [REQUIRED]
The detector for which the rule is associated.
ruleId (string) -- [REQUIRED]
The rule ID.
ruleVersion (string) -- [REQUIRED]
The rule version.
string
The detector version description.
list
The model versions to include in the detector version.
(dict) --
The model version.
modelId (string) -- [REQUIRED]
The model ID.
modelType (string) -- [REQUIRED]
The model type.
modelVersionNumber (string) -- [REQUIRED]
The model version number.
arn (string) --
The model version ARN.
string
The rule execution mode to add to the detector.
If you specify FIRST_MATCHED, Amazon Fraud Detector evaluates rules sequentially, first to last, stopping at the first matched rule. Amazon Fraud dectector then provides the outcomes for that single rule.
If you specifiy ALL_MATCHED, Amazon Fraud Detector evaluates all rules and returns the outcomes for all matched rules. You can define and edit the rule mode at the detector version level, when it is in draft status.
The default behavior is FIRST_MATCHED.
dict
Response Syntax
{}
Response Structure
(dict) --
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Updates model description.
See also: AWS API Documentation
Request Syntax
client.update_model(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
description='string'
)
string
[REQUIRED]
The model ID.
string
[REQUIRED]
The model type.
string
The new model description.
dict
Response Syntax
{}
Response Structure
(dict) --
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Updates a model version. Updating a model version retrains an existing model version using updated training data and produces a new minor version of the model. You can update the training data set location and data access role attributes using this action. This action creates and trains a new minor version of the model, for example version 1.01, 1.02, 1.03.
See also: AWS API Documentation
Request Syntax
client.update_model_version(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
majorVersionNumber='string',
externalEventsDetail={
'dataLocation': 'string',
'dataAccessRoleArn': 'string'
},
ingestedEventsDetail={
'ingestedEventsTimeWindow': {
'startTime': 'string',
'endTime': 'string'
}
},
tags=[
{
'key': 'string',
'value': 'string'
},
]
)
string
[REQUIRED]
The model ID.
string
[REQUIRED]
The model type.
string
[REQUIRED]
The major version number.
dict
The details of the external events data used for training the model version. Required if trainingDataSource is EXTERNAL_EVENTS.
dataLocation (string) -- [REQUIRED]
The Amazon S3 bucket location for the data.
dataAccessRoleArn (string) -- [REQUIRED]
The ARN of the role that provides Amazon Fraud Detector access to the data location.
dict
The details of the ingested event used for training the model version. Required if your trainingDataSource is INGESTED_EVENTS.
ingestedEventsTimeWindow (dict) -- [REQUIRED]
The start and stop time of the ingested events.
startTime (string) -- [REQUIRED]
Timestamp of the first ingensted event.
endTime (string) -- [REQUIRED]
Timestamp of the final ingested event.
list
A collection of key and value pairs.
(dict) --
A key and value pair.
key (string) -- [REQUIRED]
A tag key.
value (string) -- [REQUIRED]
A value assigned to a tag key.
dict
Response Syntax
{
'modelId': 'string',
'modelType': 'ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
'modelVersionNumber': 'string',
'status': 'string'
}
Response Structure
(dict) --
modelId (string) --
The model ID.
modelType (string) --
The model type.
modelVersionNumber (string) --
The model version number of the model version updated.
status (string) --
The status of the updated model version.
{'modelType': {'ACCOUNT_TAKEOVER_INSIGHTS'}}
Updates the status of a model version.
You can perform the following status updates:
Change the TRAINING_IN_PROGRESS status to TRAINING_CANCELLED.
Change the TRAINING_COMPLETE status to ACTIVE.
Change ACTIVE to INACTIVE.
See also: AWS API Documentation
Request Syntax
client.update_model_version_status(
modelId='string',
modelType='ONLINE_FRAUD_INSIGHTS'|'TRANSACTION_FRAUD_INSIGHTS'|'ACCOUNT_TAKEOVER_INSIGHTS',
modelVersionNumber='string',
status='ACTIVE'|'INACTIVE'|'TRAINING_CANCELLED'
)
string
[REQUIRED]
The model ID of the model version to update.
string
[REQUIRED]
The model type.
string
[REQUIRED]
The model version number.
string
[REQUIRED]
The model version status.
dict
Response Syntax
{}
Response Structure
(dict) --