Agency Compliance Status Change

Webhooks belong to the Carrier & MGA API. This event fires about an agency you appoint, and only a credential on that surface (carrier, MGA or wholesaler) can subscribe to it.

Overview

The DOWNSTREAM_ENTITY_COMPLIANCE_STATUS_CHANGE webhook is triggered when a downstream entity’s (agency) compliance status changes for any product/state combination. Webhook type: DOWNSTREAM_ENTITY_COMPLIANCE_STATUS_CHANGE

Triggers

This webhook fires when any of the following occur for a downstream entity:

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

This webhook is debounced 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.

Payload Example

{
  "webhookType": "DOWNSTREAM_ENTITY_COMPLIANCE_STATUS_CHANGE",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": [
    {
      "entity": "downstreamEntity",
      "downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
      "legalName": "Example 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 `"downstreamEntity"` for this webhook type
`downstreamEntityAssociationId`	string	The association ID linking the downstream entity to your upstream entity
`legalName`	string	Legal name of the downstream entity (agency)
`branchName`	string	Branch name of the association
`producerCode`	string (optional)	The producer code assigned to the entity. Absent when none has been assigned, or when the only value on record is an internal identifier Turris generated for its own bookkeeping rather than one you issued.
`npn`	string	National Producer Number
`products`	array	Array of products where 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"`, `"Appointment on Binding"`, `"STATE_REMOVED"`)
`statusMessages`	string[]	(Optional) Array of detailed status explanations

When a state is removed from a product’s compliance requirements, licenseStatus and appointmentStatus will both have statusName: "STATE_REMOVED".

appointmentStatus.statusName: "Appointment on Binding" is not an error state. Some states regulate appointments just-in-time: the appointment is filed once business is actually bound, rather than before the agency or agent is authorized to sell. A state in that regime reports this status, and complianceStatus for it is COMPLIANT.We do not receive binding dates, so we do not assert a breach we cannot evidence. If you branch on statusName, treat this value as passing. A comparison against "Not Appointed" will stop matching these states.

Batching

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

Start Here

Shared Endpoints

Products

Carriers

Agencies You Appoint

Contract Container Templates

Agents

Contacts

Market Contacts

Licenses

Appointments

Compliance Data Subscriptions

Compliance Status

File Documents

Policy Ingestion

Policy Transactions

Surplus Lines Filings

Diligent Effort

Webhooks

E&O/Cyber Compliance

Regulatory Actions

Tools

Agency Compliance Status Change

Overview

Triggers

Payload Example

Field Reference

Entity Fields (each element in `payload`)

Product Fields (each element in `products`)

State Fields (each element in `states`)

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

Batching

​Overview

​Triggers

​Payload Example

​Field Reference

​Entity Fields (each element in payload)

​Product Fields (each element in products)

​State Fields (each element in states)

​Status Object Fields (licenseStatus and appointmentStatus)

​Batching

Overview

Triggers

Payload Example

Field Reference

Entity Fields (each element in `payload`)

Product Fields (each element in `products`)

State Fields (each element in `states`)

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

Batching