> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agency Regulatory Action Added
> Webhook event triggered when NIPR reports a new regulatory action against an agency
## Overview
The `DOWNSTREAM_ENTITY_REGULATORY_ACTION_ADDED` webhook is triggered when the daily NIPR PDB-alerts pass finds a regulatory action against one of your agencies that Turris has not seen before.
It exists because an adverse action against an agency previously reached you only if you went looking. Regulatory actions are available on [Get Downstream Entity Regulatory Actions](/api-reference/v2/regulatory-actions/downstream-entity-regulatory-actions), but nothing told you when a new one appeared, so the only way to act on one was to poll every agency on your book. An action does not always change a compliance status either, so the compliance-status events cannot stand in for this.
This event tells you an action was newly filed, against which agency, and what it says.
**Webhook type:** `DOWNSTREAM_ENTITY_REGULATORY_ACTION_ADDED`
### Triggers
This webhook fires when the daily NIPR PDB-alerts pass records a regulatory action against an agency that was not already on file.
That is the only trigger, and the wording is deliberate — see the next section for what that excludes.
This webhook is sent **immediately**, with no debouncing, and there is one delivery per newly found action. A single
daily pass can find several, so a receiver can see a short run of deliveries — bounded by what NIPR newly reports,
which is typically small, rather than by any batching on our side.
## What does not fire this event
| Change | Use instead |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| An action already on file when an agency is first synchronised | Nothing. Backfill from [Get Downstream Entity Regulatory Actions](/api-reference/v2/regulatory-actions/downstream-entity-regulatory-actions) |
| An existing action is amended, or its disposition changes | [Agency Regulatory Action Updated](/guides/webhooks/downstream-entity-regulatory-action-updated) |
| An action is removed | Not currently signalled |
| A regulatory action against a **producer** | [Agent Regulatory Action Added](/guides/webhooks/agent-regulatory-action-added) |
| A licence or appointment changes the agency's compliance status | [Agency Compliance Status Change](/guides/webhooks/downstream-entity-compliance-status-change) |
| An AML / OFAC screening returns a match | AML / OFAC Check Status Change (`AML_OFAC_CHECK_STATUS_CHANGE`) |
### Only newly found actions are delivered
An agency's existing action history is **never** delivered by this event, and that is by design rather than an omission. Three cases all stay silent:
* the first compliance-data synchronisation after an agency is added, which loads its whole history at once
* a re-synchronisation after its NIPR data is reset, which reloads the same history
* an internal reprocessing run over previously retrieved NIPR data
If we delivered those, a bulk onboarding would announce every historical action across your whole book as though it had just happened. So this event means "newly found", and history is something you read rather than something you are told.
**Backfill before you rely on this event.** An agency added today has its existing actions loaded silently. Read
[Get Downstream Entity Regulatory Actions](/api-reference/v2/regulatory-actions/downstream-entity-regulatory-actions)
once per agency when you onboard it, then let this webhook keep you current.
## Payload Example
An action with full detail:
```json theme={null} theme={null}
{
"webhookType": "DOWNSTREAM_ENTITY_REGULATORY_ACTION_ADDED",
"upstreamEntityId": "507f1f77bcf86cd799439010",
"payload": {
"regulatoryActionId": "507f1f77bcf86cd799439013",
"actionId": "FL-2024-118820",
"npn": "7654321",
"stateCode": "FL",
"niprDataSubscriptionId": "507f1f77bcf86cd799439014",
"originOfAction": "Market Conduct Examination",
"reasonForAction": "Unfair Trade Practice",
"disposition": "License, Probation",
"dateOfAction": "2024-03-01T00:00:00.000Z",
"effectiveDate": "2024-03-15T00:00:00.000Z",
"enterDate": "2024-03-04T00:00:00.000Z",
"fileRef": "FL-OIR-55190",
"penaltyFineForfeitureInUSD": 25000,
"lengthOfOrderInDays": 180,
"downstreamEntityId": "507f1f77bcf86cd799439012",
"downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
"legalName": "RT Specialty LLC",
"branchName": "RT Specialty - Miami Beach, FL",
"producerCode": "03-e55f06b3-618c-4bf2-b578-efae34a87a6e"
}
}
```
An action where NIPR supplied none of the optional detail:
```json theme={null} theme={null}
{
"webhookType": "DOWNSTREAM_ENTITY_REGULATORY_ACTION_ADDED",
"upstreamEntityId": "507f1f77bcf86cd799439010",
"payload": {
"regulatoryActionId": "507f1f77bcf86cd799439016",
"actionId": "GA-2024-002277",
"npn": "7654321",
"stateCode": "GA",
"niprDataSubscriptionId": "507f1f77bcf86cd799439014",
"originOfAction": null,
"reasonForAction": null,
"disposition": null,
"dateOfAction": null,
"effectiveDate": null,
"enterDate": null,
"fileRef": null,
"penaltyFineForfeitureInUSD": 0,
"lengthOfOrderInDays": 0,
"downstreamEntityId": "507f1f77bcf86cd799439012",
"downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
"legalName": "RT Specialty LLC",
"branchName": "RT Specialty - Miami Beach, FL",
"producerCode": null
}
}
```
### Payload Fields
| Field | Type | Description |
| ------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `regulatoryActionId` | string | Turris's id for this action record. |
| `actionId` | string | NIPR's own identifier for the action. Part of the deduplication key — see below. |
| `npn` | string | The agency's National Producer Number. |
| `stateCode` | string | The state that took the action, e.g. `FL`, `GA`. |
| `niprDataSubscriptionId` | string | The NIPR data subscription this action was retrieved under. |
| `originOfAction` | string \| null | What surfaced the action, e.g. `Market Conduct Examination`. |
| `reasonForAction` | string \| null | Why the action was taken, e.g. `Unfair Trade Practice`. |
| `disposition` | string \| null | The outcome, e.g. `License, Probation`. |
| `dateOfAction` | string \| null | ISO-8601. When the action was taken. |
| `effectiveDate` | string \| null | ISO-8601. When the action takes effect. |
| `enterDate` | string \| null | ISO-8601. When the action was entered into NIPR. |
| `fileRef` | string \| null | The regulator's reference for supporting documentation. |
| `penaltyFineForfeitureInUSD` | number | Monetary penalty. `0` means no penalty. |
| `lengthOfOrderInDays` | number | Duration of the order. `0` means none specified **or** indefinite — NIPR does not distinguish the two. |
| `downstreamEntityId` | string, may be absent | The agency record itself. Shared by every relationship you hold with that agency. |
| `downstreamEntityAssociationId` | string, may be absent | The relationship you hold with that agency. The same identifier carried by every other webhook. **Match on this.** |
| `legalName` | string, may be absent | The agency's legal name. |
| `branchName` | string, may be absent | The branch or office name of this relationship. |
| `producerCode` | string \| null, may be absent | The producer code assigned for this relationship. |
**The seven nullable NIPR fields are always present as keys.** `null` means NIPR did not supply a value; it never
means the key is missing. So you can read `payload.disposition` without a presence check, and an empty string from
NIPR is normalised to `null` so you do not have to treat blank and absent differently.
Two of the numbers are worth reading carefully. `penaltyFineForfeitureInUSD: 0` genuinely means no penalty, but
`lengthOfOrderInDays: 0` is ambiguous in NIPR's own data — it covers both "not specified" and "indefinite". Do not
render it as "0 days".
**The entity fields are best-effort, and they all depend on one lookup.** `downstreamEntityId`, `legalName`,
`downstreamEntityAssociationId`, `branchName` and `producerCode` are resolved from your association with the
agency. If that lookup misses — an agency archived between our read and the delivery is the realistic case —
**none of them arrive**. If it hits, `downstreamEntityId` and `downstreamEntityAssociationId` are always
present and the rest are individually best-effort.
One distinction worth reading carefully: an **absent** `producerCode` key means the lookup did not resolve,
whereas `producerCode: null` means it resolved and no producer code is assigned.
## Deduplication
Key on `actionId` + `npn` + `stateCode`. Those three together identify a real-world action, and a redelivery of the
same action carries the same three values.
Do not key on `regulatoryActionId` alone if you also poll the API, because you would then hold the same action twice
under two different shapes of record.
## No fan-out across relationships
If you hold more than one relationship with the same agency, or if the same agency appears on more than one carrier's
book, each holder gets their own copy of the action and receives exactly **one** delivery for it, carrying their own
`downstreamEntityAssociationId`.
This differs from [Agency Updated](/guides/webhooks/downstream-entity-updated), where a single change to the agency
record fans out once per relationship. There is nothing to de-duplicate across relationships here.
Webhook subscriptions are per event type. Subscribing to Agency Regulatory Action Added does **not** deliver
[Agent Regulatory Action Added](/guides/webhooks/agent-regulatory-action-added) — register a separate webhook for
each event you want to receive.
## Related topics
- [Agent Regulatory Action Added](/guides/webhooks/agent-regulatory-action-added.md)
- [Agency Regulatory Action Updated](/guides/webhooks/downstream-entity-regulatory-action-updated.md)
- [Changelog](/changelog.md)