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

# Surplus Lines Filing Action Required

> Webhook event triggered when a surplus lines filing checklist escalation requires customer action

## Overview

The `SURPLUS_LINES_FILING_ACTION_REQUIRED` webhook is triggered when a surplus lines filing checklist item escalation newly transitions into the `waiting customer input` state — meaning Turris has sent a message on an escalation and is waiting for your response.

**Webhook type:** `SURPLUS_LINES_FILING_ACTION_REQUIRED`

### Triggers

This webhook fires when:

* A Turris admin sends a message on a filing checklist item escalation, setting the turn to the customer (`waiting customer input`)

<Info>
  This webhook is sent **immediately** — no debouncing is applied. Each escalation flip is a discrete event
  requiring prompt customer action.
</Info>

<Note>
  This webhook fires only when an escalation **newly enters** the `waiting customer input` state. It will not fire
  again for the same escalation until the customer replies (moving it to `waiting turris input`) and Turris
  responds again.
</Note>

## Payload Example

```json theme={null}
{
  "webhookType": "SURPLUS_LINES_FILING_ACTION_REQUIRED",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": {
    "filingId": "665f1a2b3c4d5e6f7a8b9c0d",
    "externalReference": "POL-2024-00123",
    "policyNumber": "SL-20240601-001",
    "stateCode": "TX",
    "status": "in progress",
    "actionRequired": true,
    "escalationStatus": "waiting customer input",
    "latestEscalationMessage": "Please upload the signed diligent search form for TX."
  }
}
```

## Field Reference

### Payload Fields

| Field                     | Type           | Description                                                                                             |
| ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `filingId`                | string         | The Turris ID of the surplus lines filing                                                               |
| `externalReference`       | string \| null | Your external policy reference set when the filing was created, or `null` if none was provided          |
| `policyNumber`            | string         | The policy number on the filing                                                                         |
| `stateCode`               | string         | Two-letter US state or territory code (e.g., `TX`)                                                      |
| `status`                  | string         | Current filing status at the time of the event                                                          |
| `actionRequired`          | boolean        | Always `true` for this event type                                                                       |
| `escalationStatus`        | string         | Status of the representative open escalation. Always `waiting customer input` for this event type       |
| `latestEscalationMessage` | string \| null | Body of the most recent message in the escalation thread, or `null` when no messages have been sent yet |