> ## 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 Deleted

> Webhook event triggered when an agency relationship is removed from your account

<Note>
  **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.
</Note>

## Overview

The `DOWNSTREAM_ENTITY_DELETED` webhook is triggered when an agency relationship leaves your account, by either of the two mechanisms Turris uses.

It is the counterpart to [Agency Created](/guides/webhooks/downstream-entity-created). Because that event fires as soon as you add or invite an agency, before the agency has done anything, some announced agencies are later withdrawn. Without this event you would be left holding an id that no longer resolves, with nothing to tell you why.

**Webhook type:** `DOWNSTREAM_ENTITY_DELETED`

### Triggers

This webhook fires when:

* an agency relationship is **removed**: the record is deleted outright. This happens when an invited agency that never completed its first onboarding step is deleted from the app. The id will not resolve again.
* an agency relationship is **archived**: the record is marked deleted. It stops appearing in [List Associations](/api-reference/v1/downstream-entity-associations/list-associations) and is no longer active, but it still exists internally.

`deletionType` tells you which one happened. If the distinction does not matter to you, treat both the same way: the agency is no longer active in your account.

<Note>
  **One deletion produces one delivery.** A given delete either archives the record or erases it, never both, so you
  receive a single event carrying whichever `deletionType` applies.

  Treat deliveries as idempotent by `downstreamEntityAssociationId` regardless, as you should for any webhook. In the
  event that you ever receive both types for the same association, `removed` describes the authoritative final state.
</Note>

<Info>
  This webhook is sent **immediately**, with no debouncing.
</Info>

## Payload Example

```json theme={null}
{
  "webhookType": "DOWNSTREAM_ENTITY_DELETED",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": {
    "downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
    "downstreamEntityId": "507f1f77bcf86cd799439012",
    "branchName": "RT Specialty - Miami Beach, FL",
    "path": "/507f1f77bcf86cd799439009/507f1f77bcf86cd799439011",
    "level": 1,
    "parentAssociationId": "507f1f77bcf86cd799439009",
    "ultimateParentAssociationId": "507f1f77bcf86cd799439009",
    "deletionType": "archived"
  }
}
```

## Field Reference

### Payload Fields

| Field                           | Type           | Description                                                                                                                              |
| ------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `downstreamEntityAssociationId` | string         | The ID of the association that was removed. Matches the id you received in [Agency Created](/guides/webhooks/downstream-entity-created). |
| `downstreamEntityId`            | string         | The ID of the agency record                                                                                                              |
| `branchName`                    | string         | The branch or office name of this association                                                                                            |
| `path`                          | string         | The ancestor chain as it stood at deletion                                                                                               |
| `level`                         | number         | Depth in the hierarchy. `0` is a top-level agency.                                                                                       |
| `parentAssociationId`           | string \| null | The immediate parent's association id. `null` for a top-level agency.                                                                    |
| `ultimateParentAssociationId`   | string         | The first segment of `path`                                                                                                              |
| `deletionType`                  | string         | `removed` when the record was deleted outright, `archived` when it was marked deleted                                                    |

<Note>
  This payload is intentionally smaller than the Agency Created one. It carries identification and hierarchy so you can find the record on your side and mark it, not a full description of an agency you already hold. For a `removed` deletion the agency record is deleted in the same operation, so a name lookup would return nothing anyway.
</Note>

<Note>
  **Restoring an archived agency is not signalled.** If an archived relationship is later restored it simply reappears in [List Associations](/api-reference/v1/downstream-entity-associations/list-associations); no webhook is sent. This is rare in practice. If your records must survive it, reconcile against that endpoint rather than relying on events alone.
</Note>

<Warning>
  Subscriptions are per event type. Subscribing to Agency Created without also subscribing to Agency Deleted leaves you
  with agencies in your records that no longer exist in Turris, and nothing will tell you.
</Warning>


## Related topics

- [Changelog](/changelog.md)
- [Agency Updated](/guides/webhooks/downstream-entity-updated.md)
- [Webhooks Overview](/guides/webhooks.md)