> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Risk insights

<Note>
  Risk insights is currently in **beta**.
</Note>

<Info>
  Risk Insights is an add-on feature, please contact [sales@spade.com](mailto:sales@spade.com) for more information.
</Info>

## Overview

Risk insights provide visibility into the potential risk of a transaction and the merchants involved. Our signals are designed to be leveraged during the authorization window to improve decisioning as well as for customer or account analysis. The insights returned are based on our counterparty data asset as well as extensive data analysis.

<Check>
  If you plan to use this data to prevent transactions from occurring you'll want to ensure you're sending us data in the authorization flow.
</Check>

## Understanding Risk Insights fields

Below we've provided a list of the fields we return in the `riskInsights` object.

| **Field**                     | **Risk Level** | **Definition**                                                                                                                                                                                                                                                                     |
| ----------------------------- | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **High risk entity**          | Very High      | The counterparty is known to engage in fraudulent practices                                                                                                                                                                                                                        |
| **Irregular web presence**    | High           | Has engaged in deceptive online practices or has irregular website structure or content                                                                                                                                                                                            |
| **Negative online sentiment** | Moderate       | Negative online consumer feedback associated with the counterparty                                                                                                                                                                                                                 |
| **Card acceptance history**   | See definition | Possible values:<br />`extensive`(most) <br />`established` <br />`stable` <br />`limited`<br />`very_limited `(least)<br />`null `(no data)<br /><br />Counterparties with lower levels of card acceptance history have a higher likelihood of chargebacks or fraudulent activity |
| **Risky industry**            | See definition | Industry is correlated with increased disputes (based on Spade industries)<br /><br />Example: "Casinos and Gambling" will return a value of `true`                                                                                                                                |

## Using Risk Insights

Risk Insights are best used in combination with other risk and fraud signals when making authorization or account closure decisions. Additionally, Risk Insights should only be used when a counterparty match occurs.

Below we've provided an example response for a known high-risk entity:

```json Example response {24,25,26,27,28,29,30} theme={null}
{
  "transactionInfo": {
    "type": "spending",
    "subType": null,
    "display": {
      "name": "Contentbodega.net",
      "categoryName": "Media",
      "graphic": "https://static.v2.spadeapi.com/categories/ff2e4086c1f14e368e086aadab182b19/light.png",
      "graphicSource": "category"
    },
    "thirdParties": [],
    "spendingInfo": {
      "channel": {
        "value": "digital"
      }
    },
    "transferInfo": null,
    "atmInfo": null,
    "isAccountVerification": null,
    "isPeerToPeer": null,
    "isDigitalWallet": null,
    "transactionId": "txn-1234",
    "recurrenceInfo": null,
    "riskInsights": {
      "irregularWebPresenceDetected": true,
      "negativeOnlineSentiment": true,
      "highRiskEntity": true,
      "riskyIndustry": false,
      "cardAcceptanceHistory": null
    }
  },
  "counterparty": [
    {
      "id": "f364863c-7266-30bc-aad1-7ddfbdf1edc2",
      "name": "Contentbodega.net",
      "legalName": "Gills Unlimited",
      "industry": [
        {
          "id": "004-000-000-000",
          "name": "Entertainment",
          "icon": "https://static.v2.spadeapi.com/categories/ff2e4086c1f14e368e086aadab182b19/light.png"
        },
        {
          "id": "004-008-000-000",
          "name": "Media",
          "icon": "https://static.v2.spadeapi.com/categories/ff2e4086c1f14e368e086aadab182b19/light.png"
        }
      ],
      "location": [
        {
          "id": "e713c5fa-1b31-3004-833b-4ce7a7b5c66b",
          "address": "776 Divina Vista St",
          "addressLine1": "776 Divina Vista St",
          "addressLine2": null,
          "city": "Monterey Park",
          "region": "CA",
          "postalCode": "91754",
          "country": "USA",
          "phoneNumber": "+18556600894",
          "latitude": 34.051158,
          "longitude": -118.13354,
          "matchScore": null
        }
      ],
      "matchScore": 92.37,
      "logo": null,
      "medianSpendPerTransaction": null,
      "phoneNumber": "+18556600894",
      "website": "contentbodega.net"
    }
  ],
  "transactionRuleInfo": null,
  "enrichmentId": "5d16d9ac-e91b-4ba7-bece-ec69c7aed4a9"
}
```

In the example provided, we've flagged the counterparty:

* is a  `highRiskEntity`
* has `irregularWebPresenceDetected`
* and has `negativeOnlineSentiment`

When one of our counterparty-focused fields is `true`, we have identified that the counterparty involved in the transaction has the characteristics of that field. However, a value of `false` for a field such as `highRiskEntity` does not guarantee that the merchant is *not* a high risk entity.  Additionally, a value of `null` means that there is no data available for this field for this counterparty.

<Info>
  If we do not return any industries for the counterparty, the `riskyIndustry` field will return a `null` value
</Info>

<Info>
  If we are unable to match to a counterparty each `riskInsights` field will return a `null` value
</Info>

## Feedback

We recommend using our feedback endpoints when a chargeback has occurred or when fraudulent activity related to the merchant has occurred.

* `enrichments/<enrichmentId/fraud`
* `enrichments/<enrichmentId/chargeback`

We collect the feedback you provide and use it to derive insights about the merchants and locations we return during enrichments, leveraging these insights to enhance our core enrichment API.