Agency License Expired

Overview

The DOWNSTREAM_ENTITY_LICENSE_EXPIRED webhook is triggered the day after one of your agencies’ licenses passes its renewal date. Agency Compliance Status Change fires per product and state and only on an actual status flip, so a lapse in a state you carry no requirement for never reached you. This event does. Webhook type: DOWNSTREAM_ENTITY_LICENSE_EXPIRED

Triggers

One delivery per license, on the day after its nextRenewalDate. The day after is deliberate: a state treats the renewal date as the last valid day, so a license expiring today is still valid today. daysUntilExpiration is therefore -1 on a normal delivery, not 0.

Deliveries land on a daily sweep at 05:00 America/New_York, not in real time. This is a date crossing rather than a change to a record.

What does not fire this event

Change	Use instead
The license is 60 days from renewal	Agency License Expiring
A license with no `nextRenewalDate`	Nothing. Perpetual and non-expiring licenses never fire either event
A license whose `status` is `inactive`	Nothing. NIPR has already flagged it
A license revoked or suspended for cause	Agency Regulatory Action Added, or Agency Compliance Status Change
A producer license passing its renewal date	Agent License Expired
A license renewed before the date passed	Nothing fires. The renewal moves the date and re-arms the expiring event

Licenses marked do-not-renew DO fire

If a license has been marked do-not-renew, this event still fires, which is the opposite of how Turris treats its own renewal reminders. For a carrier this is arguably the most useful case of all: the license you most want to hear about lapsing is the one someone let lapse on purpose.

There is no “expired” license status, and this payload proves it

The most confusing thing about this event: status on the payload normally reads "active" even though the license has expired. That is correct. status is copied verbatim from the NIPR PDB payload and nothing in Turris derives it from a date, so a license can sit at active with a renewal date years past. This event exists precisely because the status field cannot tell you what this tells you. Key on daysUntilExpiration being negative, or on nextRenewalDate being in the past. Never on status.

Perpetual licenses never fire

Both events are driven entirely by a range query on nextRenewalDate, so a license without one never produces a delivery. That is roughly 11% of agency licenses on the platform. Reconcile against Get Downstream Entity Licenses if you need the complete set.

Payload Example

{
  "webhookType": "DOWNSTREAM_ENTITY_LICENSE_EXPIRED",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": {
    "licenseId": "507f1f77bcf86cd799439021",
    "niprDataSubscriptionId": "507f1f77bcf86cd799439014",
    "npn": "7654321",
    "stateCode": "GA",
    "licenseNumber": "L098765",
    "licenseClassCode": "PC",
    "licenseClassName": "Property & Casualty",
    "status": "active",
    "residencyStatus": "Non-Resident",
    "issueDate": "2018-06-15T00:00:00.000Z",
    "nextRenewalDate": "2026-08-19T00:00:00.000Z",
    "linesOfAuthority": [{ "code": "PROP", "name": "Property", "status": "Active" }],
    "daysUntilExpiration": -1,
    "expiringWindowDays": 60,
    "downstreamEntityId": "507f1f77bcf86cd799439012",
    "downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
    "legalName": "RT Specialty LLC",
    "branchName": "RT Specialty - Miami Beach, FL",
    "producerCode": "03-e55f06b3-618c-4bf2-b578-efae34a87a6e"
  }
}

Note status: "active" on an expired license, and daysUntilExpiration: -1. Both are what a real delivery looks like.

Payload Fields

Field	Type	Description
`licenseId`	string	Turris’s id for this license record.
`niprDataSubscriptionId`	string	The NIPR data subscription this license was retrieved under.
`npn`	string	The agency’s National Producer Number.
`stateCode`	string	State that issued the license.
`licenseNumber`	string	The license number as filed with the state.
`licenseClassCode`	string	License class code, e.g. `PC`.
`licenseClassName`	string	Human-readable class.
`status`	string	Verbatim NIPR status. Normally `active` even here — see above.
`residencyStatus`	string	Resident or non-resident.
`issueDate`	string \| null	ISO-8601.
`nextRenewalDate`	string	ISO-8601. Always present, and in the past on this event.
`linesOfAuthority`	array	`code`, `name` and `status` per line of authority.
`daysUntilExpiration`	number	Negative on this event, normally `-1`. Do not render it as “expires in -1 days”.
`expiringWindowDays`	number	The expiring threshold, `60`. Carried here too so either delivery reconciles against the UI.
`downstreamEntityId`	string, may be absent	The agency record. Shared by every relationship you hold with it.
`downstreamEntityAssociationId`	string, may be absent	The relationship you hold with that agency. Match on this.
`legalName`	string, may be absent	The agency’s legal name.
`branchName`	string, may be absent	Branch name of this relationship.
`producerCode`	string \| null, may be absent	Producer code assigned for this relationship.

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.

There is deliberately no expirationDate field. nextRenewalDate is the only expiry date the platform holds.

Deduplication and volume

Each license matches the expired boundary on exactly one calendar day, so you receive one delivery per license per renewal cycle. No debouncing, no batching.

Size your receiver for the spike, not for the median. A typical sweep delivers single digits and the 95th percentile is under 50, but the busiest measured sweep for a single carrier carries about 1,850 deliveries of this event alone. Because renewal dates cluster on the last day of the month, this event’s spikes land on the 1st or 2nd. Return 2xx quickly and queue.

If the daily sweep does not run, that day’s licenses are not announced later. There is no catch-up pass. Reconcile against Get Downstream Entity Licenses if you need a guarantee.

Webhook subscriptions are per event type. Subscribing to Agency License Expired does not deliver Agency License Expiring — register a separate webhook for each.

Start Here

Shared Endpoints

Products

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

Webhooks

E&O/Cyber Compliance

Regulatory Actions

Tools

Overview

Triggers

What does not fire this event

Licenses marked do-not-renew DO fire

There is no “expired” license status, and this payload proves it

Perpetual licenses never fire

Payload Example

Payload Fields

Deduplication and volume

​Overview

​Triggers

​What does not fire this event

​Licenses marked do-not-renew DO fire

​There is no “expired” license status, and this payload proves it

​Perpetual licenses never fire

​Payload Example

​Payload Fields

​Deduplication and volume

Overview

Triggers

What does not fire this event

Licenses marked do-not-renew DO fire

There is no “expired” license status, and this payload proves it

Perpetual licenses never fire

Payload Example

Payload Fields

Deduplication and volume