Agency License Expiring

Overview

The DOWNSTREAM_ENTITY_LICENSE_EXPIRING webhook is triggered when one of your agencies’ licenses is 60 days from its renewal date. It exists because a lapsing agency license did not reliably reach you. Agency Compliance Status Change fires per product and state, and only when a compliance status actually flips, so a license expiring in a state you have no requirement for is silent. Nothing announced the approaching date itself. Webhook type: DOWNSTREAM_ENTITY_LICENSE_EXPIRING

Triggers

One delivery per license, on the day it is exactly 60 days from its nextRenewalDate.

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.

The 60 days here is not the 30 days in the Turris web app. The app’s own “Expiring Soon” badge appears at 30 days, so between 60 and 30 days out you will hold a license this webhook called expiring that the screen does not.Both numbers are correct for their purpose and neither is changing. Every delivery carries daysUntilExpiration and expiringWindowDays so the two surfaces reconcile. Read them rather than inferring a threshold.

What does not fire this event

Change	Use instead
The license passes its renewal date	Agency License Expired
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 reaching its renewal date	Agent License Expiring
Appointments, or product/state compliance	Agency Compliance Status Change

Licenses marked do-not-renew DO fire

If a license has been marked do-not-renew, this event still fires. Turris suppresses its own renewal reminders in that case, because there is no point nagging about a license someone decided to drop. For a carrier the reasoning inverts: an agency deliberately letting a license lapse is one of the most actionable things you can hear about your distribution book.

Perpetual licenses never fire, and there are more than you might think

Both events are driven entirely by a range query on nextRenewalDate. A license without one cannot match, so it never produces a delivery. That is roughly 11% of agency licenses on the platform. If you reconcile deliveries against your own license count you will find a gap, and this is it. Read Get Downstream Entity Licenses for the full picture.

There is no “expired” license status to key on

status is copied verbatim from NIPR and nothing in Turris derives it from a date, so a license 60 days from expiry and one that lapsed last week both normally carry status: "active". Use daysUntilExpiration and nextRenewalDate. Do not use status to infer expiry.

Payload Example

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

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, e.g. `FL`.
`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, `active` or `inactive`. Never reflects expiry — see above.
`residencyStatus`	string	Resident or non-resident.
`issueDate`	string \| null	ISO-8601.
`nextRenewalDate`	string	ISO-8601. Always present: a license without one cannot fire this event.
`linesOfAuthority`	array	`code`, `name` and `status` per line of authority.
`daysUntilExpiration`	number	Whole days to `nextRenewalDate`. Positive on this event.
`expiringWindowDays`	number	The threshold that triggered the delivery, currently `60`. Read this rather than hard-coding it.
`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. (The license GET reference currently documents an expirationDate; that field does not exist on any record and no response has ever carried a value for it.)

Deduplication and volume

Each license matches the 60-day boundary on exactly one calendar day, so you receive one delivery per license per renewal cycle. No debouncing, no batching. A renewal that moves nextRenewalDate forward re-arms the event for the new date rather than cancelling anything already sent.

Size your receiver for the spike, not for the median. The two are three orders of magnitude apart. A typical sweep delivers single digits, and the 95th percentile is still under 50 — but the busiest measured sweep for a single carrier carries about 1,850 deliveries of this event alone.Return 2xx quickly and queue the work rather than processing inline. A receiver that handles the median sweep comfortably can still fall over on a peak one.

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

Webhook subscriptions are per event type. Subscribing to Agency License Expiring does not deliver Agency License Expired — 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

Perpetual licenses never fire, and there are more than you might think

There is no “expired” license status to key on

Payload Example

Payload Fields

Deduplication and volume

​Overview

​Triggers

​What does not fire this event

​Licenses marked do-not-renew DO fire

​Perpetual licenses never fire, and there are more than you might think

​There is no “expired” license status to key on

​Payload Example

​Payload Fields

​Deduplication and volume

Overview

Triggers

What does not fire this event

Licenses marked do-not-renew DO fire

Perpetual licenses never fire, and there are more than you might think

There is no “expired” license status to key on

Payload Example

Payload Fields

Deduplication and volume