> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agency Created
> Webhook event triggered when an agency relationship is created in your account
**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](/guides/webhooks/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:
```json theme={null}
{
"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:
```json theme={null}
{
"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](/guides/webhooks/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](/which-api-is-mine#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](/api-reference/v1/downstream-entity-associations/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](/api-reference/v1/downstream-entity-associations/list-associations) rather than assuming it is stable.
## Related topics
- [Agency Updated](/guides/webhooks/downstream-entity-updated.md)
- [Agency Deleted](/guides/webhooks/downstream-entity-deleted.md)
- [Changelog](/changelog.md)