> ## 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 Compliance Status Change

> Webhook event for agent compliance status changes

## Overview

The `AGENT_COMPLIANCE_STATUS_CHANGE` webhook is triggered when an agent's compliance status changes for any product/state combination.

**Webhook type:** `AGENT_COMPLIANCE_STATUS_CHANGE`

### Triggers

This webhook fires when any of the following occur for an agent:

* Agent license is created, updated, or expires
* Agent appointment status changes
* Compliance requirements for a product/state combination are updated
* PDB (Producer Database) alerts from NIPR affect license or appointment data

<Info>
  This webhook is [debounced](/guides/webhooks#event-debouncing--batching) with a **1-minute sliding window**. After the last change in a sequence, Turris waits 1 minute before sending a consolidated webhook. A maximum cap of 30 minutes ensures delivery even during continuous activity.
</Info>

## Payload Example

```json theme={null}
{
  "webhookType": "AGENT_COMPLIANCE_STATUS_CHANGE",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": [
    {
      "entity": "agent",
      "downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
      "legalName": "Acme Insurance Agency",
      "branchName": "Main Branch",
      "producerCode": "ABC123",
      "npn": "1234567",
      "products": [
        {
          "productId": "507f1f77bcf86cd799439012",
          "productName": "Property & Casualty",
          "states": [
            {
              "stateCode": "CA",
              "complianceStatus": "COMPLIANT",
              "licenseStatus": {
                "statusName": "Licensed"
              },
              "appointmentStatus": {
                "statusName": "Appointed"
              }
            },
            {
              "stateCode": "FL",
              "complianceStatus": "NOT_COMPLIANT",
              "licenseStatus": {
                "statusName": "Missing License",
                "statusMessages": ["Required license class not found"]
              },
              "appointmentStatus": {
                "statusName": "Missing Carrier",
                "statusMessages": ["No active appointment with required carrier"]
              }
            }
          ]
        }
      ]
    }
  ]
}
```

## Field Reference

### Entity Fields (each element in `payload`)

| Field                           | Type   | Description                                                           |
| ------------------------------- | ------ | --------------------------------------------------------------------- |
| `entity`                        | string | Always `"agent"` for this webhook type                                |
| `downstreamEntityAssociationId` | string | The association ID linking the agent's agency to your upstream entity |
| `legalName`                     | string | Legal name of the downstream entity (agency) the agent belongs to     |
| `branchName`                    | string | Branch name of the association                                        |
| `producerCode`                  | string | The producer code assigned to the entity                              |
| `npn`                           | string | National Producer Number                                              |
| `products`                      | array  | Array of products where the agent's compliance status changed         |

### Product Fields (each element in `products`)

| Field         | Type   | Description                                                      |
| ------------- | ------ | ---------------------------------------------------------------- |
| `productId`   | string | The product ID                                                   |
| `productName` | string | Human-readable product name                                      |
| `states`      | array  | Array of states where compliance status changed for this product |

### State Fields (each element in `states`)

| Field               | Type   | Description                                      |
| ------------------- | ------ | ------------------------------------------------ |
| `stateCode`         | string | US state/territory code (e.g., `CA`, `TX`, `NY`) |
| `complianceStatus`  | string | Either `COMPLIANT` or `NOT_COMPLIANT`            |
| `licenseStatus`     | object | License status — see below                       |
| `appointmentStatus` | object | Appointment status — see below                   |

### Status Object Fields (`licenseStatus` and `appointmentStatus`)

| Field            | Type      | Description                                                                             |
| ---------------- | --------- | --------------------------------------------------------------------------------------- |
| `statusName`     | string    | Human-readable status name (e.g., `"Licensed"`, `"Missing License"`, `"STATE_REMOVED"`) |
| `statusMessages` | string\[] | *(Optional)* Array of detailed status explanations                                      |

<Note>
  When a state is removed from a product's compliance requirements, `licenseStatus` and `appointmentStatus` will both have `statusName: "STATE_REMOVED"`.
</Note>

## Batching

Because this webhook is debounced, a single delivery may contain **multiple agents** in the `payload` array, and each agent may have **multiple products and states** that changed. Design your handler to iterate over the full payload.