A new webhook event —
This webhook is sent immediately — no debouncing is applied.See the Producer Agreement Executed webhook documentation for payload examples and field reference.
PRODUCER_AGREEMENT_EXECUTED — is now available. It fires when a downstream entity and your upstream entity have fully executed a producer agreement (both parties have signed).Payload fields:| Field | Type | Description |
|---|---|---|
downstreamEntityAssociationId | string | The association ID |
downstreamEntityId | string | The downstream entity (agency) that executed the agreement |
producerCode | string | null | The producer code for this association |
branchName | string | The branch name of the association |
The
Why NPN instead of an entity ID? A single NPN can be linked to multiple downstream entity associations and downstream entities across your network. The NPN is the natural, universal identifier for any NIPR-driven operation and lets you look up all relevant records for that producer. Use
ENTITY_COMPLIANCE_DATA_SYNCHRONIZED webhook payload no longer includes an entityId field. It has been replaced by npn (National Producer Number).What changed:| Field | Before | After |
|---|---|---|
entityId | string (MongoDB ObjectId) — was always "undefined" due to a bug | Removed |
npn | (not present) | string — the NPN of the synchronized entity |
niprDataSubscriptionId to retrieve the specific subscription record via the Compliance Data Subscriptions API.Note: The previous entityId field was always sent as the string "undefined" due to a bug — it did not contain a valid entity ID. If you were reading this field, update your handler to use npn instead.Action required: Update your webhook handler to read npn instead of entityId. See the Compliance Data Synchronized documentation for the updated payload reference.Look up National Producer Numbers directly through the API. Send up to 20 NPNs in a single request and instantly find out whether each NPN belongs to an agency (firm), an individual agent, or is not recognized by NIPR — along with entity details like name, resident states, FEIN, and date of birth.See the Validate NPNs endpoint for full details.
When the same
Add Downstream Entity or Invite Downstream Entity request is submitted multiple times simultaneously, the API now returns a clear 409 Conflict response instead of an unhandled 500 Internal Server Error.The response includes the error code transient_transaction_error with the message: “This request has already been processed. A duplicate concurrent request was detected.”No action required — this is a non-breaking improvement. If you are handling 409 status codes already, you will now receive this new error code for concurrent duplicate requests.The
New fields added:
AGENT_COMPLIANCE_STATUS_CHANGE and DOWNSTREAM_ENTITY_COMPLIANCE_STATUS_CHANGE webhook payloads now use a hierarchical structure grouped by entity → product → state, replacing the previous flat structure.What changed:| Aspect | Previous | New |
|---|---|---|
| Structure | Flat — one object per state | Nested — products[].states[] per entity |
| Association field | upstreamDownstreamAssociationId | downstreamEntityAssociationId |
licenseStatus | Plain string (e.g., "Licensed") | Object with statusName and optional statusMessages |
appointmentStatus | Plain string (e.g., "Appointed") | Object with statusName and optional statusMessages |
isStateRemovedFromComplianceRequirements | Boolean field | Removed — state removal is now indicated by statusName: "STATE_REMOVED" |
legalName— Legal name of the downstream entitybranchName— Branch name of the associationproductName— Human-readable product name (alongsideproductId)statusMessages— Optional array of detailed status explanations onlicenseStatusandappointmentStatus
Compliance status change webhooks (
AGENT_COMPLIANCE_STATUS_CHANGE and DOWNSTREAM_ENTITY_COMPLIANCE_STATUS_CHANGE) are now debounced with a 1-minute sliding window. When a change is detected, Turris waits for 1 minute of inactivity before sending the webhook. If additional changes occur within that window, the timer resets. A maximum cap of 30 minutes ensures delivery even during continuous activity.This means there is a minimum ~1 minute delay between a data change and webhook delivery. The debouncing consolidates rapid sequences of changes (e.g., PDB alert processing, bulk operations) into a single webhook with a batched payload.ENTITY_COMPLIANCE_DATA_SYNCHRONIZED webhooks are not affected — they are still sent immediately.See the Webhooks guide for details.Webhook requests are no longer encrypted with AES-256-GCM. Instead, payloads are sent as plaintext JSON (
Action required: Update your webhook endpoint to verify the
Content-Type: application/json) and signed with HMAC-SHA256 using your client secret.Each request now includes two new headers:| Header | Description |
|---|---|
X-Turris-Signature | HMAC-SHA256 hex signature computed over {timestamp}.{body} |
X-Turris-Timestamp | Unix timestamp (seconds) when the request was signed |
X-Turris-Signature header instead of decrypting the request body. See the Webhooks guide for code examples.If you request the licenses for an
agentId that does not exist, the API now returns an error message that explicitly
states that an agent could not be found.For each agent or agency (downstream entity association) we now auto-populate the
niprDataSubscription field,
allowing you to immediately see the compliance synchronization status.Call the new endpoint with a specific email to receive a sign-in URL that you can share with the contact owning that email. They can use it to sign into the Agency application to either complete the onboarding flow with your organization or manage your market relationship by updating contacts, agents, or documents.The response returns a
404 error if the agency or a contact with the email at the agency could not be found.You can now find your associated downstream entities by email domain or a specific email address.
The
GET /downstream-entity-associations endpoint now accepts an emailDomain query param. Clients can find all of
their associated agencies by the email domain of the associated agency contacts.We have moved all requests into the parent domain, simplifying the authentication collection structure.
All protected API endpoints now accept either authentication method:
| Method | Header | Format |
|---|---|---|
| OAuth (Preferred) | Authorization | Bearer {jwt_token} |
| Restricted Access Token | x-restricted-access-token | {your_token} |
- If only a Bearer token is provided, OAuth authentication is used
- If only a Restricted Access Token is provided, token authentication is used
- If both headers are present, OAuth is attempted first; if it fails, the API falls back to Restricted Access Token authentication
- Both methods produce the same authenticated context (
upstreamEntityIdandupstreamEntityMemberId)
This new endpoint allows clients to retrieve all active surplus lines licenses for a downstream entity association,
filtering by FEIN and state code.
Previously, the
GET agency/agent endpoints returned all records, including those that are soft-deleted. Since our
users are only interested in active records, we now exclude any records with isDeleted: true.Agents and Downstream Entity Associations can now be found and filtered either by their NPN or by their license number
and state code. Both filter types are mutually exclusive. If a license number is provided, a valid state code must be
provided as well.
The new regulatory actions endpoints allow you to retrieve any regulatory actions for your downstream entity
associations and their agents.
Retrieve all appointments for your downstream entity associations and their agents. You can filter by
stateCode and
status.Previously, the licenses endpoint returned all active licenses. We have added the
status filter as a query param.
Now, this endpoint returns active, inactive, or all licenses. Future iterations may add additional status values.After an agent or downstream entity has been added to the tenancy, you can call this endpoint to retrieve the latest compliance data associated with the entity’s NPN. The subscription includes daily updates of all compliance data.This endpoint runs asynchronously — it returns a success response immediately but the sync process may be queued and/or processing for minutes. Two solutions are available:
- Webhook: Subscribe to a webhook and get notified when the compliance data sync completes
- Polling: Poll the compliance data subscription status endpoint until
entityInfo.status: success
Retrieve all active licenses for an agent or a downstream entity association. Optionally, provide
stateCode to
filter by state.- URL params were changed to reflect the new
downstreamEntityAssociationIdnomenclature -stateCodequery string is now optional; in absence of this param, the endpoint returns the compliance status for all states
Users can now upload any document and associate it with any downstream entity via the downstream entity association
ID.
The URL path and query strings for the E&O/Cyber compliance endpoint have changed.
The
GET and POST endpoints for the Downstream Entity Associations resource now return the association data alongside the downstream entity detail. The _id field is the downstreamEntityAssociationId and should be thought of as the main identifier for any association with a downstream entity.What changed:- URL path and query strings have changed
- The response body now includes the association data that describes the relationship between the Downstream and the Upstream Entity
The
GET and POST endpoints for the Agent resource now return the agent detail as well as the top-level association resource. Information describing the relationship between two resources is returned as sibling fields of the agent property.What changed:- URL path and query strings have changed
- The response body now includes the association data that describes the relationship between the Agent and the Upstream Entity
If you have created a template producer agreement in the web app with custom fields (e.g. an agency-specific
commission number), you can now assign those values when sending a request to the Invite Downstream Entity endpoint.
The Invite Downstream Entity endpoint now accepts an optional
downstreamEntityId field. If provided, the endpoint
creates a new downstream entity association with the existing downstream entity. If not provided, it creates both a
new downstream entity and a new association.This endpoint allows you to invite downstream entities to your organization. It creates a new downstream entity and
association. The downstream entity receives an email invitation to complete the onboarding process.
Subscribe to webhooks to receive real-time notifications when events occur in your organization. Available events include:
- Downstream entity association created/updated
- Agent created/updated
- Compliance data sync completed
- Document uploaded
- Contract signed
Upload, retrieve, and manage documents associated with downstream entities. Documents can be categorized by type
(e.g., E&O policy, cyber policy, W-9) and are automatically linked to the appropriate downstream entity association.
Agents can now be added to downstream entity associations with assignment status tracking. The API supports:
- Adding agents to agencies
- Updating agent assignment status (pending, approved, rejected)
- Tracking assignment history
- Managing agent authority by product and state
Create and manage producer agreement templates with custom fields. Templates can be assigned to downstream entities
during the invitation process, with custom field values populated at invitation time.
New endpoints provide aggregated compliance data for dashboard views:
- Overall compliance status by downstream entity
- License expiration summaries
- E&O/Cyber policy status
- Regulatory action counts
- Appointment status summaries
New batch endpoints allow you to perform operations on multiple entities at once:
- Batch invite downstream entities
- Batch add agents
- Batch update authority
- Batch sync compliance data