Labels API
This article explains how the labels API enables you to send information to the reporting and monitoring dashboards in Microsoft Dynamics 365 Fraud Protection.
The labels API enables you to send fraud or non-fraud signals to Fraud Protection. This data is used for model training, model performance evaluation, and reporting. The labels API is a general API that labels assessment events by using either individual transaction or event IDs, or entities such as user or payment instrument.
- Any fraudulent transactions that are escalated by your customers
- Fraudulent activity or account abuse that is identified by your review team
- Any offline analysis (such as behavior analysis or discovered connections to existing fraud cases)
- TC40/SAFE signals that are received
- Reversal of a previous fraud signal after it's identified as non-fraud based on the latest available information
- Chargebacks/refunds that are received
- Chargeback reversal after a dispute
We recommend that you use the chargeback and refund API to provide information that is related to chargebacks and refunds. For more information about supported events, see Dynamics 365 Fraud Protection Service.
- Fraudulent account or payment instrument information that is identified by your review team
- Account takeover scenarios that are escalated by your customers
Attribute | Type | Description |
---|---|---|
labelObjectType | Enum Expected values: PURCHASE, ACCOUNTCREATION, ACCOUNTLOGIN, ACCOUNT, PI, EMAIL |
This attribute indicates how extensively you want to flag a label. For example, you might want to mark a single transaction as fraudulent, or you might want to mark all a user account's transactions as fraudulent. Depending on the object type, Fraud Protection flags related transactions or events as fraud or non-fraud. For example, if the labelObjectType value is PURCHASE, ACCOUNTCREATION, or ACCOUNTLOGIN, Fraud Protection labels specific transactions. If the value is ACCOUNT or PI, Fraud Protection flags all the transactions that are related to the user account or payment instrument. |
labelObjectId | String | The identifier that corresponds to the value of the labelObjectType attribute. Fraud Protection uses this value to find related transactions and events. The IDs of the label object types are as follows:
This attribute is very important, because Fraud Protection uses it to identify the original assessment event. Therefore, the value must match the original transaction or event ID. |
labelSource | String | The source of label information. Some suggested values are ManualReview if a fraud label is identified by the review team, and CustomerEscalation if a customer complains about a falsely rejected transaction (in other words, a false positive). TC40/SAFE data is another source for label data. |
isFraud | Boolean | This attribute indicates whether the label is fraud or non-fraud. If no value is provided, Fraud Protection uses true as the default value. |
reasonText | String | The reason for labeling something fraud or non-fraud. You can safely ignore reasons if you have limited information about your label sources. Alternatively, depending on your label workflows, you can map some scenarios to some of these values. |
labelReasonCodes | String | Normalized reason codes or reason codes that are received from the payment processor. You can safely ignore this attribute if you don't have reason details. Some suggested values are Processor Response Code, Bank Response Code, Fraud Refund, Account Takeover, Payment Instrument Fraud, Account Fraud, Abuse, Friendly Fraud, Account Credentials Leaked, and Passed Account Protection Checks. |
labelState | String | The kind of label that you're sending. This attribute is used especially if you're reversing a previous fraud signal or false positive. In both cases, you'll set isFraud to false. However, the state can help identify false positive labels. |
Processor | String | The name of the payment processor. |
eventTimeStamp | DateTime (ISO 8601 format) | The label-identified timestamp. If the API is integrated directly with the label detection process, and you call the label API as soon as a review agent flags a transaction as fraud, the value can be the current timestamp. This value is especially important for determining the order of events when there are multiple labels. For example, if a purchase or account creation transaction is labeled as fraud but is later labeled as non-fraud, Fraud Protection will refer to this value to determine which of the two labels is more recent and therefore correct. |
effectiveStartDate | DateTime (ISO 8601 format) | The effective start and end dates are intended to enrich labels that are wider than one transaction (and that usually have a labelObjectType value of ACCOUNT) to limit the impact of those labels to a specific timeframe. For example, in account compromise scenarios, these dates specify the timeframe that you want to label the transactions or events in. |
effectiveEndDate | DateTime (ISO 8601) format | The effective start and end dates are intended to enrich labels that are wider than one transaction (and that usually have a labelObjectType value of ACCOUNT) to limit the impact of that label to a specific timeframe. For example, in account compromise scenarios, these dates specify the timeframe that you want to label the transactions or events in. |
Amount | Double | The total fraud amount. You can skip this value if no amount is available. For example, in account creation and sign-in scenarios, there might not be an associated amount. In the purchase scenario, Fraud Protection will use the transaction amount. |
Currency | String | The three-character International Organization for Standardization (ISO) currency code that is related to the amount. |
Your review team identified suspicious transactions by looking at the payment information.
{
"labelObjectType": "PURCHASE",
"labelObjectId": "<purchase transaction Id, i.e., purchaseId>",
"labelSource": "ManualReview",
"isFraud": true,
"labelState": "Fraud",
"eventTimeStamp": "2022-10-04T16:24:36.045Z",
"_metadata": {
"trackingId": "<guid or identifier>",
"merchantTimeStamp": "2022-10-04T20:44:14.706Z"
}
}
A user lost access to their account, and a malicious actor used that user's credentials to sign in. Later, the user recovered their credentials and reported a compromised time interval.
{
"labelObjectType": "ACCOUNT",
"labelObjectId": "<userId>",
"labelSource": "CustomerEscalation",
"isFraud": true,
"reasonText": "AccountCompromise",
"labelState": "Fraud",
"eventTimeStamp": "2022-10-04T12:21:46.326Z",
"effectiveStartDate": "2022-10-03T10:00:00.000Z",
"effectiveEndDate": "2022-10-04T12:16:00.000Z",
"_metadata": {
"trackingId": "<guid or identifier>",
"merchantTimeStamp": "2022-10-04T12:21:46.326Z"
}
}
You blocked a suspicious user sign-in, and later the user called the support team to get unblocked. If the support team reviews the evidence, confirms that the user is the legitimate user, and unblocks the user, you must send a label that has a FalsePositive state.
{
"labelObjectType": "ACCOUNT",
"labelObjectId": "<userId>",
"labelSource": "CustomerEscalation",
"isFraud": false,
"reasonText": "AccountCompromise",
"labelState": "FalsePositive",
"eventTimeStamp": "2022-10-04T16:21:46.326Z",
"_metadata": {
"trackingId": "<guid or identifier>",
"merchantTimeStamp": "2022-10-04T16:21:46.326Z"
}
}