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

# Broker Velocity

> Flag a merchant that many brokers are submitting at once, read the band, and test your integration

Broker velocity flags a merchant being submitted to many funders at once by many brokers. It finds other submissions across the Heron platform for the same owner in the 24 hours before yours, counts the distinct email domains they were sent from, and reports a band. Your own email domains are not counted. It also reports the highest band the same owner reached on earlier deals in the last 30 and 90 days, so a merchant shopped heavily last month still shows up when the last 24 hours are quiet.

The count only looks back. A submission made after yours does not change your result, though it counts towards that later submission's own result. It runs as the `broker_velocity` enricher. See the [Fraud Detection overview](https://docs.herondata.io/integrations/fraud-detection/overview.md) for how it fits with the fraud network.

## Thresholds

Each band is a minimum count of distinct sending domains, set per account. The defaults are 5 for `high`, 4 for `medium` and 3 for `low`. Contact your Heron rep to change them, for example after a backtest on your own deals.

## Integrating

Broker velocity runs inside your Heron workflow on every submission you send, so there is nothing extra to call.

### Prerequisites

* Submissions flowing into Heron, by email or over the API. See the [Quickstart](https://docs.herondata.io/get-started/quickstart.md) to send them over the API.
* Broker velocity enabled for your account and added to your workflow. Contact your Heron rep.
* Owner details on the submission, usually from its ISO application. Without them it is not run. Sole proprietors are not measured, and neither are submissions to broker accounts.

### Act on it in your policy

A high band can route the deal to review or decline it. Policies read the **Broker velocity** variable (`broker_velocity`), which is `High`, `Medium`, `Low` or `None`. Sole proprietors read as `None`. It is missing when the deal has no owner information, your account is a broker, or the measurement did not run. Ask your Heron rep to add the check.

### Read the result

The `enricher.succeeded` [webhook](https://docs.herondata.io/api-reference/webhooks.md) fires when it finishes, with `enricher_name` `broker_velocity`. Then fetch the result:

```python app.py theme={null}
import requests

BASE_URL = "https://app.herondata.io"
API_KEY = "key_xxxxxxxx"
end_user_heron_id = "eus_xxxxxxxx"

response = requests.get(
    f"{BASE_URL}/api/end_user_enrichers/{end_user_heron_id}/enricher_results/broker_velocity",
    headers={"x-api-key": API_KEY},
)
response.raise_for_status()
velocity = response.json()["result"]
print(velocity["broker_velocity_signal"])
```

The endpoint returns `404` until it has run for the submission.

## Understanding the result

```json theme={null}
{
  "broker_velocity_signal": "high",
  "not_run_reason": null,
  "peak_30d_broker_velocity_signal": "medium",
  "peak_30d_seen_on": "2026-10-21",
  "peak_90d_broker_velocity_signal": "high",
  "peak_90d_seen_on": "2026-08-14"
}
```

| Field | Meaning |
| - | - |
| `broker_velocity_signal` | `high`, `medium`, `low`, `excluded_sole_prop`, or `null` (below `low`, or not run). |
| `peak_30d_broker_velocity_signal`, `peak_30d_seen_on` | The highest signal any deal for the same owner reached in the 30 days before, and when. |
| `peak_90d_broker_velocity_signal`, `peak_90d_seen_on` | The same over 90 days. |
| `not_run_reason` | Why it did not run, e.g. `Not run: missing owner information`. |

| `broker_velocity_signal` | Meaning |
| - | - |
| `high` | At or above your account's high threshold. |
| `medium` | At or above your medium threshold. |
| `low` | At or above your low threshold. |
| `excluded_sole_prop` | Not measured: sole proprietors are excluded. |
| `null` | Below your low threshold, or the enricher did not run. |

The response is the band only. The brokers and the number of submissions are never shared.

## Testing your integration

You can get a `high` result without real data. Create a submission with business legal name `HERON SANDBOX FRAUD RING LLC` and owner `HERON SANDBOX` / `FRAUD RING`, following the [fraud network testing steps](https://docs.herondata.io/integrations/fraud-detection/fraud-network.md#testing-your-integration). Broker velocity returns `high` at your account's high threshold and records no measurement.

Any other made-up identity runs the live count, so it usually returns no signal or is not run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.