Agency Created

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_CREATED webhook is triggered when an agency relationship is created in your account. It exists for the parent/child case. When you onboard an agency underneath one that has already executed a producer agreement, no PRODUCER_AGREEMENT_EXECUTED fires for the child: the parent signed once, months earlier, and the child has no agreement of its own. This event tells you the child exists, and carries enough context to determine whether it is covered. Webhook type: DOWNSTREAM_ENTITY_CREATED

Triggers

This webhook fires when an agency relationship is created in your account:

you add an agency
you invite an agency
an agency arrives through a CSV bulk upload
a company syncs in from HubSpot

It fires before the agency has responded to an invitation or completed any onboarding step. If you need the “fully onboarded” signal instead, use Producer Agreement Executed.

This webhook is sent immediately, with no debouncing. A bulk upload therefore produces one delivery per agency in the file, so a large import produces a burst proportional to its size. Size your receiver to absorb or queue it.

Payload Example

A child agency, under a parent whose producer agreement is already executed:

{
  "webhookType": "DOWNSTREAM_ENTITY_CREATED",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": {
    "downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
    "downstreamEntityId": "507f1f77bcf86cd799439012",
    "branchName": "RT Specialty - Miami Beach, FL",
    "legalName": "RT Specialty LLC",
    "npn": "1234567",
    "producerCode": "ABC123",
    "externalId": "CRM-40912",
    "path": "/507f1f77bcf86cd799439009/507f1f77bcf86cd799439011",
    "level": 1,
    "parentAssociationId": "507f1f77bcf86cd799439009",
    "ultimateParentAssociationId": "507f1f77bcf86cd799439009",
    "ultimateParentAgreementExecuted": true,
    "creationPath": "addition"
  }
}

A top-level agency is its own ultimate parent:

{
  "webhookType": "DOWNSTREAM_ENTITY_CREATED",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": {
    "downstreamEntityAssociationId": "507f1f77bcf86cd799439009",
    "downstreamEntityId": "507f1f77bcf86cd799439008",
    "branchName": "RT Specialty - Chicago, IL (National Parent)",
    "legalName": "RT Specialty LLC",
    "npn": "7654321",
    "producerCode": null,
    "externalId": null,
    "path": "/507f1f77bcf86cd799439009",
    "level": 0,
    "parentAssociationId": null,
    "ultimateParentAssociationId": "507f1f77bcf86cd799439009",
    "ultimateParentAgreementExecuted": false,
    "creationPath": "invitation"
  }
}

Determining whether a new agency is covered

Read ultimateParentAgreementExecuted:

true: the top of this agency’s hierarchy has an executed producer agreement. Nothing further to do.
false: not yet. Wait for a Producer Agreement Executed event whose downstreamEntityAssociationId equals this payload’s ultimateParentAssociationId.

You do not need to call the API to answer this question, and you do not need to parse path yourself. ultimateParentAssociationId is already the first segment.

Field Reference

Payload Fields

Field	Type	Description
`downstreamEntityAssociationId`	string	The ID of the association between the agency and your upstream entity. The same identifier used across the carrier surface and in every other webhook. The agency surface calls this same value `upstreamDownstreamAssociationId` (see the same records, two vocabularies).
`downstreamEntityId`	string	The ID of the agency record itself
`branchName`	string	The branch or office name of this association
`legalName`	string?	The agency’s legal name. Optional: omitted if the lookup could not be completed. Not optional because an agency can lack one.
`npn`	string?	The agency’s National Producer Number. Optional for the same reason as `legalName`.
`producerCode`	string \| null	The producer code assigned for this association. `null` if none has been assigned yet, or if the only value on record is an internal identifier Turris generated for its own bookkeeping rather than one you issued.
`externalId`	string \| null	Your own identifier for this association, if you supplied one when creating it.
`path`	string	Materialized ancestor chain, `/rootId/parentId/currentId`. Segments are association ids, so each one can be fetched from Get Association.
`level`	number	Depth in the hierarchy. `0` is a top-level agency, `1` is its child, and so on.
`parentAssociationId`	string \| null	The immediate parent’s association id. `null` for a top-level agency.
`ultimateParentAssociationId`	string	The first segment of `path`. A top-level agency is its own ultimate parent, so this equals `downstreamEntityAssociationId`.
`ultimateParentAgreementExecuted`	boolean	Whether the ultimate parent has an executed producer agreement, as of this event.
`creationPath`	string	How the relationship was created: `invitation`, `addition`, `bulk-upload`, or `hubspot sync`. Immutable.

ultimateParentAgreementExecuted is a snapshot taken when the agency was created, not a live field. A true cannot go stale. A false can, because the ultimate parent may sign later, and that is exactly what the Producer Agreement Executed event tells you.It always refers to the root of the hierarchy, never to the nearest ancestor that happens to have signed. For a two-level hierarchy those are the same thing. For deeper hierarchies they can differ, and path gives you every ancestor if you need to check them yourself.

path is also a snapshot. Moving an agency to a different parent rewrites it, and that change is not currently signalled by a webhook. If you cache the hierarchy, re-read it from List Associations rather than assuming it is stable.

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

Payload Example

Determining whether a new agency is covered

Field Reference

Payload Fields

​Overview

​Triggers

​Payload Example

​Determining whether a new agency is covered

​Field Reference

​Payload Fields

Overview

Triggers

Payload Example

Determining whether a new agency is covered

Field Reference

Payload Fields