Agent License Expired

Overview

The AGENT_LICENSE_EXPIRED webhook is triggered the day after one of your producers’ licenses passes its renewal date. This is the event behind “did you know your license lapsed in Oregon”. Agent Compliance Status Change fires per product and state and only on an actual status flip, so a lapse in a state you have no requirement for, or one covered by another license the producer holds, never reached you. Webhook type: AGENT_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	Agent 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	Agent Regulatory Action Added, or Agent Compliance Status Change
An agency license passing its renewal date	Agency License Expired
A license renewed before the date passed	Nothing fires. The renewal moves the date and re-arms the expiring event

Licenses the producer chose not to renew DO fire

If a producer marked a license do-not-renew, this event still fires, which is the opposite of how Turris treats its own renewal reminders (those are suppressed, because there is no point nagging someone about a license they decided to drop). For a carrier the reasoning inverts, and this is arguably the single most useful case: the license you most want to hear about lapsing is the one the producer 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 9% of producer licenses on the platform. Reconcile against Get Agent Licenses if you need the complete set.

Payload Example

{
  "webhookType": "AGENT_LICENSE_EXPIRED",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": {
    "licenseId": "507f1f77bcf86cd799439020",
    "niprDataSubscriptionId": "507f1f77bcf86cd799439014",
    "npn": "1234567",
    "stateCode": "OR",
    "licenseNumber": "0K12345",
    "licenseClassCode": "PC",
    "licenseClassName": "Property & Casualty",
    "status": "active",
    "residencyStatus": "Non-Resident",
    "issueDate": "2019-04-01T00:00:00.000Z",
    "nextRenewalDate": "2026-08-19T00:00:00.000Z",
    "linesOfAuthority": [{ "code": "PROP", "name": "Property", "status": "Active" }],
    "daysUntilExpiration": -1,
    "expiringWindowDays": 60,
    "agentId": "507f1f77bcf86cd799439015",
    "downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
    "legalName": "RT Specialty LLC",
    "branchName": "RT Specialty - Miami Beach, FL"
  }
}

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 producer’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.
`agentId`	string, may be absent	The producer. Use it to call Get Agent Licenses.
`downstreamEntityAssociationId`	string, may be absent	The agency relationship the producer writes under.
`legalName`	string, may be absent	Legal name of the agency, not of the producer.
`branchName`	string, may be absent	Branch name of that relationship.

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.

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 2,800 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 Agent Licenses if you need a guarantee.

Webhook subscriptions are per event type. Subscribing to Agent License Expired does not deliver Agent 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 the producer chose not to 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 the producer chose not to 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 the producer chose not to 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