## Device Risk Velocity Metrics

When the Digital Intelligence module is included in a call to the Evaluation endpoint, the API response contains a `velocityMetrics` object. This object contains historical metrics based on the number of unique email addresses, phone numbers, first names, and last names that have been included in API calls to Evaluation endpoint with a given `di_session_token`.

```json
{
  // ...
  "observations": {
    "firstSeen": "2021-xx-xx 21:09:54",
    "lastSeen": "2021-xx-xx 20:06:53"
  },
  // highlight-start
  "velocityMetrics": {
    "historicalCount": {
      "email": {
        "uniqueCount": 1,
        "uniqueSharePercent": 100
      },
      "mobileNumber": {
        "uniqueCount": 1,
        "uniqueSharePercent": 100
      },
      "surName": {
        "uniqueCount": 1,
        "uniqueSharePercent": 100
      },
      "firstName": {
        "uniqueCount": 1,
        "uniqueSharePercent": 100
      }
    }
  }
  // highlight-end
}
```

## How velocity metrics are calculated

Velocity metrics are calculated using transaction data from the past 90 days. Velocity data considers only historical data and does not include the current transaction in its counts. The metrics reflect the total number of times and unique share percentage that each of the following Personal Identifiable Information (PII) elements that have been seen with the `di_session_token`:

- email
- phone number
- first name
- last name

This information is returned in the API response in the `uniqueCount` and `uniqueSharePercent` fields:

- `uniqueCount`: The number of unique email addresses, phone numbers, first names, or last names that have been seen with the `di_session_token`. A high `uniqueCount` can be risky and could indicate that many different PII are being used with the same device.
- `uniqueSharePercent`: The percentage of transactions (excluding the current transaction) that have used the email address, phone number, first name, or last name included in the RiskOS™ API call along with the `di_session_token`. A low `uniqueSharePercent` can be risky and could indicate that the consumer is not the device’s primary user.

> 📘
>
> **Note**:
>
> The first RiskOS™ API call for a `di_session_token` will not return `velocityMetrics` because there is no historical data. However, metrics from the first call will be included in the API response for the second call.

### Example

In the following example, nine transactions have been made with a `deviceSessionId` using the email address `john@example.com`. The `velocityMetrics` object in the API response shows the `uniqueCount` as `1` for `email` and the `uniqueSharePercent` as `100` because this email address is the only one that has been used to make transactions.

```json
"velocityMetrics": {
  "historicalCount": {
    "email": {
      // highlight-start
      "uniqueCount": 1,
      "uniqueSharePercent": 100
      // highlight-end
    }
    // ...
  }
}
```

Let's say a tenth transaction is made with the `deviceSessionId` using a different email address, `john1@example.com`. The `uniqueCount` is still `1` as velocity metrics only considers historical data and does not include the current transaction in its metrics. The `uniqueSharePercent` is `0` because this email address has not been used with any historical transactions.

```json
"velocityMetrics": {
  "historicalCount": {
    "email": {
      // highlight-start
      "uniqueCount": 1,
      "uniqueSharePercent": 0
      // highlight-end
    }
    // ...:...
  }
}
```

If another transaction is made using `john1@example.com`, the `uniqueCount` increments to `2` because two different email addresses have been used to make transactions for this `deviceSessionId`. The `uniqueSharePercent` is `10` because `john1@example.com` has been included in one out of ten transactions (10%) for this `deviceSessionId`.

```json
"velocityMetrics": {
  "historicalCount": {
    "email": {
      // highlight-start
      "uniqueCount": 2,
      "uniqueSharePercent": 10
      // highlight-end
    }
    // ...
  }
}
```