> ## 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.
# Agent Regulatory Action Added
> Webhook event triggered when NIPR reports a new regulatory action against a producer
## Overview
The `AGENT_REGULATORY_ACTION_ADDED` webhook is triggered when the daily NIPR PDB-alerts pass finds a regulatory action against one of your producers that Turris has not seen before.
It exists because an adverse action against a producer previously reached you only if you went looking. Regulatory actions are available on [Get Agent Regulatory Actions](/api-reference/v2/regulatory-actions/agent-regulatory-actions), but nothing told you when a new one appeared, so the only way to act on one was to poll every producer on your book. A licence lapse or an adverse ruling 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 whom, and what it says.
**Webhook type:** `AGENT_REGULATORY_ACTION_ADDED`
### Triggers
This webhook fires when the daily NIPR PDB-alerts pass records a regulatory action against a producer 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 a producer is first synchronised | Nothing. Backfill from [Get Agent Regulatory Actions](/api-reference/v2/regulatory-actions/agent-regulatory-actions) |
| An existing action is amended, or its disposition changes | [Agent Regulatory Action Updated](/guides/webhooks/agent-regulatory-action-updated) |
| An action is removed | Not currently signalled |
| A regulatory action against an **agency** | [Agency Regulatory Action Added](/guides/webhooks/downstream-entity-regulatory-action-added) |
| A licence or appointment changes the producer's compliance status | [Agent Compliance Status Change](/guides/webhooks/agent-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
A producer'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 a producer is added, which loads their whole history at once
* a re-synchronisation after their NIPR data is reset, which reloads the same history
* an internal reprocessing run over previously retrieved NIPR data
If we delivered those, onboarding a book of producers would announce every historical action 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.** A producer added today has their existing actions loaded silently. Read
[Get Agent Regulatory Actions](/api-reference/v2/regulatory-actions/agent-regulatory-actions) once per producer when
you onboard them, then let this webhook keep you current.
## Payload Example
A criminal action, the case this event was built for:
```json theme={null} theme={null}
{
"webhookType": "AGENT_REGULATORY_ACTION_ADDED",
"upstreamEntityId": "507f1f77bcf86cd799439010",
"payload": {
"regulatoryActionId": "507f1f77bcf86cd799439013",
"actionId": "AL-2024-004412",
"npn": "1234567",
"stateCode": "AL",
"niprDataSubscriptionId": "507f1f77bcf86cd799439014",
"originOfAction": "Background Check",
"reasonForAction": "Criminal Record/History",
"disposition": "License, Revocation",
"dateOfAction": "2024-03-01T00:00:00.000Z",
"effectiveDate": "2024-03-15T00:00:00.000Z",
"enterDate": "2024-03-04T00:00:00.000Z",
"fileRef": "AL-DOI-88214",
"penaltyFineForfeitureInUSD": 5000,
"lengthOfOrderInDays": 365,
"agentId": "507f1f77bcf86cd799439015",
"downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
"legalName": "RT Specialty LLC",
"branchName": "RT Specialty - Miami Beach, FL"
}
}
```
An administrative action where NIPR supplied none of the optional detail:
```json theme={null} theme={null}
{
"webhookType": "AGENT_REGULATORY_ACTION_ADDED",
"upstreamEntityId": "507f1f77bcf86cd799439010",
"payload": {
"regulatoryActionId": "507f1f77bcf86cd799439016",
"actionId": "TX-2024-000913",
"npn": "1234567",
"stateCode": "TX",
"niprDataSubscriptionId": "507f1f77bcf86cd799439014",
"originOfAction": null,
"reasonForAction": null,
"disposition": null,
"dateOfAction": null,
"effectiveDate": null,
"enterDate": null,
"fileRef": null,
"penaltyFineForfeitureInUSD": 0,
"lengthOfOrderInDays": 0,
"agentId": "507f1f77bcf86cd799439015",
"downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
"legalName": "RT Specialty LLC",
"branchName": "RT Specialty - Miami Beach, FL"
}
}
```
### 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 producer's National Producer Number. |
| `stateCode` | string | The state that took the action, e.g. `AL`, `TX`. |
| `niprDataSubscriptionId` | string | The NIPR data subscription this action was retrieved under. |
| `originOfAction` | string \| null | What surfaced the action, e.g. `Background Check`, `Bankruptcy Notices`. |
| `reasonForAction` | string \| null | Why the action was taken, e.g. `Criminal Record/History`. |
| `disposition` | string \| null | The outcome, e.g. `License, Revocation`. |
| `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. |
| `agentId` | string, may be absent | The producer. Use it to call [Get Agent Regulatory Actions](/api-reference/v2/regulatory-actions/agent-regulatory-actions). |
| `downstreamEntityAssociationId` | string, may be absent | The agency relationship the producer writes under. The same identifier carried by every other webhook. |
| `legalName` | string, may be absent | Legal name of the **agency** the producer belongs to, not of the producer. |
| `branchName` | string, may be absent | Branch name of that relationship. |
**The seven nullable 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.** `agentId`,
`downstreamEntityAssociationId`, `branchName` and `legalName` are resolved from your association with the
producer's 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, `downstreamEntityAssociationId` is always present and the rest are
individually best-effort.
Absent means "we could not resolve this", never a statement about the data. Re-read from the API rather than
inferring anything from an absent field.
**One caveat.** When a producer works under more than one of your agencies, the agency fields name an arbitrary one
of those relationships, because a single NIPR subscription is shared across them. `agentId` is exact; treat
`downstreamEntityAssociationId` as one of possibly several. Match on `agentId`.
## 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 carriers
If the same producer appears on more than one carrier's book, each carrier holds their own copy of the action, and each
receives exactly **one** delivery for it, carrying their own `downstreamEntityAssociationId`.
This differs from [Agency Updated](/guides/webhooks/downstream-entity-updated), where a single change fans out across
every relationship you hold. There is nothing to de-duplicate across relationships here.
Webhook subscriptions are per event type. Subscribing to Agent Regulatory Action Added does **not** deliver
[Agency Regulatory Action Added](/guides/webhooks/downstream-entity-regulatory-action-added), and it does not
deliver [Agent Regulatory Action Updated](/guides/webhooks/agent-regulatory-action-updated) either. Register a
separate webhook for each event you want to receive, and take the Updated event alongside this one so a revised
filing does not go unheard.
## Related topics
- [Agency Regulatory Action Added](/guides/webhooks/downstream-entity-regulatory-action-added.md)
- [Agent Regulatory Action Updated](/guides/webhooks/agent-regulatory-action-updated.md)
- [Changelog](/changelog.md)